[lazarus] Documentation added to the site

[Michael Van Canneyt]

On Thu, 16 Mar 2000, Michael A. Hess wrote:

> Curtis White wrote:
> > 
> > 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.
> 
> 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.

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.