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.

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.

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?

How are the sections in the final (HTML) documents generated? What's required that e.g. a Uses, Declaration or Inheritance section is created? All that seems to be created automatically, according to the "5.1 HTML Output" description?

What's required to get links to other entries? Can FPDoc create links automatically, or must all links be inserted explicitly?

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?

@all:

Should all empty entries, for overridden methods etc., be removed from the docs, so that FPDoc can do its work properly, i.e. the inherited entry is shown?

The documentation of properties is complicated, due to the many involved items: property name, type, getter, setter, field. IMO everything should be described in the property entry itself, all related descriptions should be linked to that entry. When the property type is an set, and this type is not used elsewhere, the enum members also should be described in the property description.

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

Can somebody provide templates or refer to *good* description entries, usable as templates?

DoDi

Feel free to make suggestions in the bugtracker. I will consider them on a case by case basis.

Under no circumstances should you submit a huge patch which changes a lot of unrelated things. Small is beautiful.

Beware:
I don't use the GUI editors for the RTL/FCL docs, because they completely mess up indentation, spacing and what not.

Feel free to supply patches.

I don't concern myself with style, but if you have suggestions: please... You can always submit a separate .css file.

How are the sections in the final (HTML) documents generated? What's required that e.g. a Uses, Declaration or Inheritance section is created? All that seems to be created automatically, according to the "5.1 HTML Output" description?

I don't understand this question ?

What's required to get links to other entries? Can FPDoc create links automatically, or must all links be inserted explicitly?

It generates some links by itself (overview pages, class declarations, inheritance trees), all others must be inserted manually.

For overridden methods, I can imagine adding still a 'Overrides XXX in class YYY'
just under the declaration, where XXX and YYY are links to the documentation of the overridden method XXX and parent class YYY.

The parameter and result entries should be supplied, because they are outputted in the HTML docs. However, in the RTL documentation which was created before fpdoc existed, the parameter and result entries have never been made.

In new units, I do document the parameters and results.

Michael.

A logfile can be obtained by redirecting the output to a file.

For building FCL/RTL docs, you probably need a unix system. Although maybe building the html reference docs will work on windows too.

What's required to fix the unresolved links to RTL and FCL? How to get the .xct files?

The xct files are normally in the RTL/HTML docs.

Michael.

Clarification: I mean the Lazarus (LCL...) documentation, not that of FPDoc. I can update that documentation myself, no need to bother others with patches.

Where is the FPDocEditor documentation? ;-)

I have no idea how to write .css files, and why FireFox inserts so much whitespace into the pages :-(

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

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.

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

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

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>

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

-------------------------

Can somebody provide templates or refer to *good* description entries, usable as templates?

I don't understand. Please explain further.

Regards,
- Graeme -

Exactly this difference!

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

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.

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

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.

If you are referring to the description in the tiOPF source code - those are NOT used by 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.

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.

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.

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?

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.

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

Hans-Peter Diettrich wrote

A look at the HTML source reveals a reference to ../fpdoc.css. This seems to be wrong, no .css in that directory.

I believe this was done to minimize duplication of the .css file. So only one "top level" fpdoc.css file is needed, even for multiple packages (eg: RTL, FCL, LCL etc).

When copied to the expected location, both your as well as the supplied fpcdoc.css cure the excess whitespace.

Glad to here it has been fixed in the latest FPC then.

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

If you are referring to the double spaced HTML help located in (the default URL's Lazarus IDE looks at):

http://lazarus-ccr.sourceforge.net/docs/rtl/index.html http://lazarus-ccr.sourceforge.net/docs/fcl/index.html http://lazarus-ccr.sourceforge.net/docs/lcl/index.html

That is not Michael van Canneyt's work. It is the responsibility of the person maintaining the lazarus-ccr project (I think Vincent is in charge there). I suggest you file a Lazarus bug report or something.

Yes I know fpdoc looks at the source code, but what I meant was that it doesn't look at descriptions or comments in the source code. The only "documentation" fpdoc uses, is from the XML files. So even though the tiOPF project has duplicate documentation information in the XML and source code, only the XML ones are used [by fpdoc].

structure. I regularly shudder, when I read descriptions like: "Create initializes the local fields, then calls the inherited constructor" :-(

Documentation is a slow and boring process! I am currently documenting fpGUI units one by one. I take my hat off for the work Michael has done with the RTL, FCL and PDF docs. That is an incredible amount of work that doesn't just happen over night.

But I agree with your sentiment, good documentation is vital to any project. The Lazarus project is seriously lacking in that department. At to make matters worse for the Lazarus project, the documentation is fragmented. Some on the wiki, some in source code, some in fpdoc XML etc.

Regards,
- Graeme -

Right, but then the references should go to that docs/html/fpdoc.css. This must be fixed in the HTML generator.

Documentation is a slow and boring process! I am currently documenting fpGUI units one by one. I take my hat off for the work Michael has done with the RTL, FCL and PDF docs. That is an incredible amount of work that doesn't just happen over night.

I know that, having once translated and corrected the Win3.0 API documentation. That's why I want to revise the documentation now, in the hope that my work will stay in the repository.

DoDi

Hans-Peter Diettrich wrote

I can update that documentation myself, no need to bother others with patches.

????

Patches are invented for managing concurrent updates.....

-Michael

Which is only possible for a patch. :) :) :)

-Michael

No, that's Commit ;-)

DoDi