Greetings,

I have added documentation to the web site. It is Pasdoc generated files of the LCL. At this point it is very dry since not much in the way of documentation has every been added to the source code. This is something I would appreciate the developers start doing. When every you are in a given piece of code just add a little bit of description for the various classes and procedures found there. It makes the documentation all that much better.

As always the new files for translation are available for anyone who would like to add translations for the new files or for a new language.

I also am just about finished with the developer news add on. This section will allow registered developers to update their own news section with information about what they are doing. A general news page will list several of the most recent additions added by the developer.

I'll announce when this feature is finished.

If any one has any other news or snapshots they would like to see added to the site please send them my way. :-)

Hello!

Thursday, March 16, 2000, 1:16:59 AM, You wrote:

Currently i am trying to figure out why lazarus crashes on win32 when you try to create any window other than the main one... but -

MAH> As always the new files for translation are available for anyone who MAH> would like to add translations for the new files or for a new language.

i can add a Russian translation - if you think we need it.

Regards, Alexandr A. Alexandrov ()

There are templates in the lcl/templates directory that contain comments that were designed specifically for pasdoc. But there is a simple problem with the way our files are setup and pasdoc (unless someone has fixed this since the last time I looked at pasdoc). That is that pasdoc does not pick up the .inc files. So it grabs all the documentation out of the .pp files but misses the .inc files. Most of the procedures are documented in the .inc files. Like I said, maybe this has been fixed since last I looked at pasdoc, but if not, then that is probably why the documentation looks really thin.

Curtis

Hi!

Although I've tried to document most methods there's not much in the documentation right now. Could you give an example of how to write pasdoc compliant docs?

BTW: I hate to write documentation in the interface section since from my point of view it almost ever hides the information I'm looking for when searching through class declarations. Thus I'd prefer to have the docs in the implementation part but then it's difficult to document variables and properties. Anybody here who has a solution for this topic?

bye,

Stefan

So far I've just been lurking, so I have to say hi and thank you for your hard work on Lazarus. I'm looking forward to contributing something when life gets a bit less hectic :-)

On Thu, 16 Mar 2000, Michael A. Hess wrote: I would also warn against the using of the implementation section; it will mean that you must extend pasdoc to a full-blown pascal parser, because the implementation can have very difficult constructs.

I haven't used pasdoc, so I don't know how it works but I've usually written comments to the implementation section in the following way:

procedure TSmile.Paint;
//  This one draws the TSmile-component
//  This is the main comment area and everything
//  I write here is picked up as comments.
begin
  Canvas.RectFill(Rect(0,0,Width,Height)); //Clean it
  DrawSmile; // :-) <- that's it
  ....
end;

Then I have a small program that finds all those comments where pos('//',SourceLine)=1 and makes html-code from those including the procedure- and functions-lines.

The documentation looks like:

procedure TSmile.Paint

This one draws the TSmile-component
This is the main comment area and everything
I write here is picked up as comments.

procedure TSmile. and so on.....

/jarto

It picks up the .inc files but our .inc files are just of the implementation portion of the code. If I understand how Pasdoc works it is pulling it's information from the interface portion of the code. So in other words it isn't even trying to read any information in the .inc files.

It would be nice if it could pull procedure and function descriptions from the implementation section since this would make the code cleaner to read. Putting complex descriptions with in the class definition seems to get somewhat messy to me. Maybe Marco can look into that when he gets back into Pasdoc in about a week or so.

The above is the reason why the Pasdoc output is rather thin. While some documentation has been done in the implementation sections, where the procedures are placed, the interface sections are largely devoid of any comments or descriptions.

I plan on taking one set of files say buttons.pp or dialog.pp and edit that as an example of what needs to be done to work with Pasdoc. I'll announce when I have that done and commited.

I agree with regards to how Pasdoc uses comments in the current design. I takes whatever the comment was previous to the item and uses that as the description. At present you can place comments on the same line AFTER the item but Pasdoc uses it as the description for the following item. Ex:

TSomething = class
  public
    item1 : Boolean;   // A boolean flag
    item2 : Interger;  // A counter
    item3 : String;    // A file name
  end;

In this case Pasdoc assigns the descriptions as follows

item1 -
item2 - A counter
item3 - A file name

Maybe if we can get Marco to modify Pasdoc so that any comments on the same line as the item being defined is used as the description for that item. This would allow us to add useful comments to the code not only for Pasdoc but for regular reading and it wouldn't clutter up trying to read the code when programming.

Maybe we can get him to also use the comments before the procedures and functions in the implementation section as well. This would allow detail comments about the procedure to reside with the actual code and also not clutter up the interface section.

Another problem that I see is that currently Pasdoc only puts in the descriptions for "public" items within a class. I would like to see all items in the documentation no matter what security level they are at. Maybe this could be an option as to what level of field security is shown in the documentation.

Hello!

Thursday, March 16, 2000, 8:50:16 PM, You wrote:

MAH> "Alexandr A. Alexandrov" wrote

> > i can add a Russian translation - if you think we need it.

MAH> Hey if you would like to do it, great! I really don't know if we do or MAH> do not need it but I do now that the site does get a fair number of hits MAH> from that part of the world.

Well, you can send me the files in English and explanations, if there is anything specific...

Regards, Alexandr A. Alexandrov ()

That's pretty straight foward. I would guess we could add something like that to PASDOC so we get the best of PASDOC and that.

I personally like to add my comments (if I add any) to the implementation portion, not to the class. Adding all the comments to the class makes it difficult to read. Adding them right to the procedure's in the class seems like a better/cleaner way to go and would be easier to read.

Shane

>> 03/16/00 07:29AM >>>

So far I've just been lurking, so I have to say hi and thank you for your hard work on Lazarus. I'm looking forward to contributing something when life gets a bit less hectic :-)

On Thu, 16 Mar 2000, Michael A. Hess wrote: I would also warn against the using of the implementation section; it will mean that you must extend pasdoc to a full-blown pascal parser, because the implementation can have very difficult constructs.

I haven't used pasdoc, so I don't know how it works but I've usually written comments to the implementation section in the following way:

procedure TSmile.Paint;
//  This one draws the TSmile-component
//  This is the main comment area and everything
//  I write here is picked up as comments.
begin
  Canvas.RectFill(Rect(0,0,Width,Height)); //Clean it
  DrawSmile; // :-) <- that's it
  ....
end;

Then I have a small program that finds all those comments where pos('//',SourceLine)=1 and makes html-code from those including the procedure- and functions-lines.

The documentation looks like:

procedure TSmile.Paint

This one draws the TSmile-component
This is the main comment area and everything
I write here is picked up as comments.

procedure TSmile. and so on.....

/jarto

_________________________________________________________________ To unsubscribe: mail with
"unsubscribe" as the Subject
archives at http://www.miraclec.com/list_archives/lazarus

I might add that we have a 'permanent' FPC representative in Russia, which keeps the Russian message file up to date and who runs the russian mirror. Michael A. Baikov - another michael :-)...

And last but not least, I speak Russian, so it will be fun to see a Russian Free Pascal site :-)

Michael.

"Alexandr A. Alexandrov" wrote

i can add a Russian translation - if you think we need it.

Hey if you would like to do it, great! I really don't know if we do or do not need it but I do now that the site does get a fair number of hits from that part of the world.

Marco Schmidt wrote

There is of course the (untested) option of putting all descriptions in a separate file to keep the interface section 'clean'.

The current documentation doesn't talk about that. It is only indicated in the --help action of the program. How do you use the -c feature? What do you put in the external file?

There is the 'include private' switch (-p IIRC, don't have access to anything here) that overrides the default settings of not including any private items.

Ooops. Sorry about that I overlooked that feature.

You're not the first who asked for this! I'll think about how I'll solve it...

There is of course the (untested) option of putting all descriptions in a separate file to keep the interface section 'clean'.

Maybe we can get him to also use the comments before the procedures and functions in the implementation section as well. This would allow detail comments about the procedure to reside with the actual code and also not clutter up the interface section.

I'm not sure about touching the implementation section... That would require quite some additional work.

There is the 'include private' switch (-p IIRC, don't have access to anything here) that overrides the default settings of not including any private items.

As I said before, I hope to be back on pasdoc in two weeks!

Regards,
Marco

I have been working with marco on Pascdoc. (I did the TeX support) The proposition I made him was to have:

  { @file(somefile,sometag) }
  Procedure MyNiceProcedure;

It would look for the description in file 'somefile' at tag 'sometag'

This way the source file would remain thin, and all docs would be separate. Don't forget that lots of comments also slow down the compiler, which must scan all of them.

I would also warn against the using of the implementation section; it will mean that you must extend pasdoc to a full-blown pascal parser, because the implementation can have very difficult constructs.

The way I see it is:
In the interface you put comments on WHAT it does. In the implementation you put commens on HOW it does it and WHY.

The user is interested in the interface, and not in the implementation...

And even if you don't put any commenst in the interface, pasdoc gives you at least a nice overview of what is available (types, procs) in the unit.

Michael.