[fpc-devel] fpdoc enhancement

[Graeme Geldenhuys]

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>
-----------  end  -----------------


Obviously how we define the fpdoc variables are up for discussion.

Regards,
  - Graeme -