Show quoted text 21 lines
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.
