[Lazarus] FPDoc content and editor

[michael.vancanneyt at wisa.be]

On Thu, 25 Aug 2011, Hans-Peter Diettrich wrote:

> A look at the current documentation revealed much crap, sorry :-(
>
> Many entries do not correspond to the implementation, or hide the essential 
> information stored in inherited entries, others contain useful information in 
> the wrong place.

Feel free to make suggestions in the bugtracker. I will consider them on a
case by case basis.

Under no circumstances should you submit a huge patch which changes a lot of 
unrelated things. Small is beautiful.

Beware: 
I don't use the GUI editors for the RTL/FCL docs, because they
completely mess up indentation, spacing and what not.

> Before I start updating the docs, here some questions:
>
> @Michaël:
>
> FPDoc is documented to show the inherited description, when no element tag is 
> present for overridden methods. That's nice, but the FPDocEditor should do 
> the same, or at least should allow to display the inherited entry; this will 
> both make the FPDoc editor more useful while coding, and will allow to find 
> out where information really is required for an overridden method.

Feel free to supply patches.

> The HTML docs contain many empty lines, e.g. the entries in a class 
> Declaration are separated by two empty lines, what makes the docs hard to 
> read without a lot of scrolling. The same applies to the [...(by name)] 
> pages. A look at the HTML source suggests improper use or style of tables 
> (<tr>...), perhaps using lists (<ul>?) would result in better readable 
> output?

I don't concern myself with style, but if you have suggestions: please...
You can always submit a separate .css file.

> How are the sections in the final (HTML) documents generated?
> What's required that e.g. a Uses, Declaration or Inheritance section is 
> created? All that seems to be created automatically, according to the "5.1 
> HTML Output" description?

I don't understand this question ?

> What's required to get links to other entries? Can FPDoc create links 
> automatically, or must all links be inserted explicitly?

It generates some links by itself (overview pages, class declarations,
inheritance trees), all others must be inserted manually.

For overridden methods, I can imagine adding still a 
'Overrides XXX in class YYY'
just under the declaration, where XXX and YYY are links to the documentation
of the overridden method XXX and parent class YYY.

>
> What's the purpose of Parameter and Result entries? Are these automatically 
> inlined into the procedure description (Arguments section)? Or should they be 
> removed from the source files, with descriptions moved into the procedure 
> description itself?

The parameter and result entries should be supplied, because they are
outputted in the HTML docs. However, in the RTL documentation which was
created before fpdoc existed, the parameter and result entries have never
been made.

In new units, I do document the parameters and results.

Michael.