[Lazarus] FPDoc content and editor

[Hans-Peter Diettrich]

Graeme Geldenhuys schrieb:
> On 08/25/2011 09:22 AM, Hans-Peter Diettrich wrote:
>> 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.
> 
> 
> By that, do you mean...
> 
>   http://opensoft.homeip.net:8080/tiopf/core/index.html
> 
> vs
> 
>   http://lazarus-ccr.sourceforge.net/docs/lcl/index.html
> NOTE:
> The LCL unit listing is double spaced, whereas the tiOPF unit listing
> has no extra spacing between lines.

Exactly this difference!

> If that is what you meant, then it is a CSS issue that crept up
> somewhere. A while back I commented on this and first thought it was the
> HTML output writer that changed, but after some investigation, it would
> found that it is a CSS file issues.
> 
> Here is a direct link to the CSS file I used for the tiOPF HTML
> documentation.
> 
>   http://opensoft.homeip.net:8080/tiopf/core/fpdoc.css

I'm not sure how to use that file. Shall it replace the css in the 
docs/lcl folder, before compiling the docs?


>> 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>?).
> 
> 
> You mean like this:
> 
>   http://opensoft.homeip.net:8080/tiopf/core/tiobject/tperobjectstate.html

Like that, but it looks as if the declaration in the source code 
contains the description. This is not the case for most LCL enums, or 
the description is insufficient.

> The enum type and it's various values are described as follows in the
> XML documentation file.
> 
> 
> -------------------------
> 
> <element name="TPerObjectState">
> <short>The possible states of a TtiObject descendant in memory</short>
> <descr><printshort id="TPerObjectState"/>.</descr>
> </element>

I don't fully understand the use of <printshort> here. Does it simply 
duplicate the short description of the same entry?

> <element name="TPerObjectState.posEmpty">
> <short>The object has been created, but not filled with data from the
> DB</short>
> </element>

A short description may be useful here, but sometimes a longer 
description is required. Then I see several solutions:

1) Extend the short description of the enum members, into a full 
description. This will allow to use printshort in the enum description.

2) Add links to the element descriptions in the enum description. This 
requires that the user follows these links, for a longer description of 
every element.

3) Add the longer element description to the enum description. This 
requires to link the element descriptions to the enum description, or to 
duplicate the element description (not desireable).


>> Can somebody provide templates or refer to *good* description entries, 
>> usable as templates?
> 
> I don't understand. Please explain further.

Something like you provided above. Sample code for describing various 
element types, e.g. procedures (with parameters), enums (with members), 
properties...

It may be sufficient to refer to one such element in the existing 
documentation, so that every contributor can find out how he should 
structure similar descriptions. In other cases, where multiple 
descriptions are involved (e.g. property, getter, setter...), a sample 
description structure for all these elements should be provided.

Bad examples may be provided as well, but that may be dangerous.


I already found 
<http://wiki.lazarus.freepascal.org/LCL_Documentation_Roadmap>, which 
could be extended with an style guide and beforementioned examples.

DoDi