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

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.

Michael Van Canneyt wrote

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>

You guys also think of everything! :-)
One minor typo in your example. It needs the closing "/".

<printshort id="TCustomListView.Change"/>

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.

I like these ideas.... Should save on a lot of typing and potential typos.

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.

I stand corrected! :-)

Regards,
- Graeme -

Weeell, we're lazy developers, so it comes natural ;-)

One minor typo in your example. It needs the closing "/". <printshort id="TCustomListView.Change"/>

Correct, my mistake.

Yes.

Michael.

Looking at the RTL docs, just answered my second question. Links inside <descr> tags. I didn't know you could do that! Excellent. I though the <link> tag could only be used in the <seealso> tag.

Graeme.