[Lazarus] FPDoc content and editor

[Hans-Peter Diettrich]

michael.vancanneyt at wisa.be 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