[fpc-pascal] Extending FPDoc

[Michael Van Canneyt]

On Fri, 16 Sep 2005 dhkblaszyk at zeelandnet.nl wrote:

> Hi there,
> 
> For Lazarus I have made a tool called LazDoc that attempts to integrate a
> documentation editing tool with the IDE. Depending on the position of the
> cursor on the source editor, the appropriate documentation tag is searched
> and then selected in the editor.
> Anyway, while I was working on the tool, I realized that some additional
> tags would be very usefull.
> 
> todo:
> Here you can enter todo items in your code. Later after documentation
> generation, an additional summary page is generated with an overview of
> the todo items.
> 
> notes:
> Here you can enter notes in your source. They coud be remarks for instance
> for other developers, or just plain reminders for yourself.
> 
> I don't know how others feel about this, but it's sure I cannot do it
> myself. Perhaps someone can help me here?? Just an explanation on how to
> handle and where to look would also be nice.

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
really use it inside the file, just use special formatting of comments:
<!-- %TODO% Some note text for authors -->

In lazarus, you could even store the TODO in a separate file. If I'm correct,
Lazarus has already a TODO system.

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.

At the level of the package, you can nest topics:

<topic name="PackageNotes">
  <short>Notes For this Package</note>
  <topic name="Note1">
  <short>Remember to do this</short>
  <descr>more note text</descr>
  </topic>
</topic>

At the level of a module, you can't nest topics, but there you could use a 
description list:

<topic name="ModuleNotes">
<short>Remember to do this</short>
<descr>
  <dl>
  <dt>Note 1</dt><dd>more note text</dd>
  </dl>
</descr>
</topic>
it's easy to parse with the XML engine.

You should be able to get a long way with this without needing to change anything in FPDoc.

Michael.