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
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
