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
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
