[Lazarus] FPDoc content and editor

[Hans-Peter Diettrich]

Graeme Geldenhuys schrieb:
> On 25/08/2011, Hans-Peter Diettrich  wrote:
>>>   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?
> 
> 
> You can simply copy it over the existing .css file after you generated
> the HTML output. By default fpdoc doesn't supply a fpdoc.css file as
> far as I know. Neither does it generate one in the HTML output.

A look at the HTML source reveals a reference to ../fpdoc.css. This 
seems to be wrong, no .css in that directory. When copied to the 
expected location, both your as well as the supplied fpcdoc.css cure the 
excess whitespace.

@Michael: can you fix that, or do you need an bug report?


>>>   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.
> 
> If you are referring to the description in the tiOPF source code -
> those are NOT used by fpdoc at all. FPDoc only looks at what is inside
> the related XML files (like the sample I posted).

The Declaration sections look like copied from the source code, they 
even include the source filename and line number of the declaration. 
This feature requires that all source files are passed to fpdoc, and 
then errors like "forms.pp not found" can result.


>>> <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?
> 
> Yes, that is the style I prefer. The short description is a short one
> line comment - usable in HTML ouput like a class interface.
> 
> The <descr> is then the full description of the feature - starting
> with the short description, and continuing from there. Sometimes the
> information in the short description is enough detail, or contains
> important details, so that's why I duplicate it with the <printshort>
> tag.

I don't like that duplication, but that's a matter of taste. I also 
don't like the repetition of the item name, at the begin of the short 
description, but with printshort even this may make sense.



> The tiTokenLibrary unit in tiOPF uses (I think) all features of fpdoc.

It's not about features, it's about content - information and document 
structure. I regularly shudder, when I read descriptions like:
"Create initializes the local fields, then calls the inherited 
constructor" :-(

DoDi