[Lazarus] FPDoc content and editor

[Hans-Peter Diettrich]

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.

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.

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?

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?

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

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?


@all:

Should all empty entries, for overridden methods etc., be removed from 
the docs, so that FPDoc can do its work properly, i.e. the inherited 
entry is shown?

The documentation of properties is complicated, due to the many involved 
items: property name, type, getter, setter, field. IMO everything should 
be described in the property entry itself, all related descriptions 
should be linked to that entry. When the property type is an set, and 
this type is not used elsewhere, the enum members also should be 
described in the property description.

Similarly for enums and sets, where should the description be stored? 
IMO the enum declaration is the right place for the description of all 
elements, where the elements should be described in a list (<dl>?).

Can somebody provide templates or refer to *good* description entries, 
usable as templates?

DoDi