[Lazarus] FPDoc content and editor

[Graeme Geldenhuys]

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. Well,
this was last time I checked, things might have changed in recent
months.


>>
>>   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 tiOPF project
used to use pasdoc many years ago as the class document generator. We
simply haven't deleted those messy inline comments yet - it's on a low
priority todo list.


>> <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.



>> <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:


This is a limitation of fpdoc's HTML output writer (and maybe some
other output formats too). The fpdoc HTML output writer doesn't used
the <descr> element anywhere for enum elements documentation, only the
<short> element is used. For the enum type itself, both <short> and
<descr> are used.


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

The tiTokenLibrary unit in tiOPF uses (I think) all features of fpdoc.
Images, unit overview, long and short description for enum types,
class declaration, method parameter descriptions, example code etc.

http://opensoft.homeip.net:8080/tiopf/core/titokenlibrary/index.html


It is a small unit, so it might make for a good example of fpdoc usage.

Note:
I haven't generated tiOPF's class documentation in any other fpdoc
format (HTML only), so I don't know how those other output writers
handle images. The tags I used in the description section of the XML
file are all fpdoc tags though - I never use HTML specific tags
embedded in such descriptions. So in theory all fpdoc output writers
should handle the XML documentation file correctly.


-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net