[email protected] schrieb:
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.
Clarification: I mean the Lazarus (LCL...) documentation, not that of
FPDoc. I can update that documentation myself, no need to bother others
with patches.
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.
Where is the FPDocEditor documentation? ;-)
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.
I have no idea how to write .css files, and why FireFox inserts so much
whitespace into the pages :-(
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.
Fine.
Some more questions:
How do I create local HTML documentation, e.g. for an preview before
committing changes? Does there exist a wiki entry or other useful
documentation?
Using the build_lcl_docs application only builds the LCL documentation,
with a bunch of error messages. How can a logfile be obtained? How can
documentation be built for other packages (FCL, IDE...)? Is LazDE
useful/usable for that purpose?
What's required to fix the unresolved links to RTL and FCL?
How to get the .xct files?
DoDi
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
