[fpc-pascal] Extending FPDoc

[Michael Van Canneyt]

On Sun, 18 Sep 2005, Darius Blaszijk wrote:

> On Fri, 2005-09-16 at 22:17, Michael Van Canneyt wrote:
> > I'd rather you keep these todo separate. It'll slow down parsing
> > (which is already horribly slow) and I see no added value. If you must
> Could you elaborate on that?? I don't see a problem in adding a tag.
> While indeed it will slow down parsing by a few mSec per node, the
> generated pages will not suffer from this at all. Instead more useful
> text will be shown for developers. Because that's the audience the
> documentation is meant for right??

If it is useful for everyone (i.e. end-users), why don't you put it in 
the documentation itself ?

> 
> > In lazarus, you could even store the TODO in a separate file. If I'm correct,
> > Lazarus has already a TODO system.
> True, but it does not show in the documentation obviously.

TODO's should not be in the documentation. The documentation is 
for the end-users of code. The TODO is for the developer of the code.
That is why you should use lazarus' TODO system for it.

John Doe is not interested in reading things like
'Optimize the code to use faster TFPList instead of TList'
He wants to know what a call does, or what the effect is 
of setting a property. How this is achieved is not of interest.

> 
> > What concerns notes, there is already a <topic> node. It is meant for 'Extra' text.
> > You can use that inside the package or module node.
> Ok, good to hear, but can I use it also at the element level?? Although
> pakage notes are usefull, they will never get into that much detail as
> element notes. What I have in mind are detailed notes per element on
> certain aspects in the code.

You can't. It is not meant for that, either. 

Keep in mind that the documentation is meant for end-users, 
not for the maintainers of the code. For the maintainers, 
there is the TODO list of Lazarus.

Michael.