[fpc-devel] fpdoc enhancement

[Michael Van Canneyt]

On Wed, 30 Aug 2006, Graeme Geldenhuys wrote:

> Hi,
>
> Could it be possible and would it be a good idea to do the following.
>
> Each element in the documentation *.xml file we have <short> and
> <descr> tags.  <short> is normally a one line (abstract) description.
> I find that most of the time when I document my code, I repeat the
> short comment as the first line in my <descr> tag and then extend the
> description. I have seen the same thing done in the FPC docs and
> Lazarus docs.
>
> Would it not maybe be a good idea to create a fpdoc variable or
> something that can be used in the <descr> tag which will include the
> <short> description when generating the documentation.
>
> I believe JavaDoc and the documentation program of Qt uses something like 
> this.
>
> I guess an example will explain it better:
>
> ------  before.xml -----------
> <element name="TCustomListView.Change">
> <short>This is a internal procedure called when an item has changed.</short>
> <descr>This is a internal procedure called when an item has changed.
> This procedure makes sure the OnChange() event is called if the user
> assigned a method to this event.</descr>
> </element>
> -----------  end  -----------------
>
> Can then be changed to something like this.
>
> ------  after.xml -----------
> <element name="TCustomListView.Change">
> <short>This is a internal procedure called when an item has changed.</short>
> <descr>{@short}  This procedure makes sure the OnChange() event is
> called if the user assigned a method to this event.</descr>
> </element>

Try the printshort tag:

  <descr><printshort id="TCustomListView.Change">. This procedure makes sure the OnChange() event is
   called if the user assigned a method to this event.</descr>

The lazdoc editor could be enhanced to have an option which includes this tag by default
if the description node is empty. I could even add this option to the makeskel program.

But it's definitely not common practice in the RTL or FCL docs.
RTL/FCL practice is to start the description with the name of 
the element.

Michael.