[Lazarus] Documentation style

[Mattias Gaertner]

On Sat, 23 Jul 2011 13:20:42 +0100
Hans-Peter Diettrich <DrDiettrich1 at aol.com> wrote:

>[...]
> Style related are field names like "childs", which IMO should read 
> "Children" 

Yes.

>[...]
> Often I come across "circles", referring to circular unit references. 
> IMO the correct term instead would be "loops", in e.g. "avoid loops".

AFAIK the correct term in graph theory is "cycle".

  
> Many descriptions only describe the obvious, like method names expressed 
> in more words. Such descriptions are quite useless, and should be 
> replaced by more informative ones. I'd suggest to remove all these 
> descriptions (replace by a todo-marker?), until somebody can describe 
> the elements better.

I doubt that this should be done for all.
What if the method just does what the name says?

 
> The final documenation shows the element name, so that the short 
> description should not duplicate this name, IMO. Opinions?

What do you purpose instead?

 
> Related: the FPDoc Editor IMO should always show the short description, 
> above the pages. Then it's easier to e.g. avoid duplication of the short 
> description in the long description.

The short description is already shown above the long description.

>[...] 
> The same for parameters, whose separate descriptions are not normally 
> accessible in e.g. the FPDoc editor.

ToDo. Please create a feature request.


>[...]
> As already mentioned in another mail, all links to #LCL are broken now. 

I changed the #LCL to #LCLBase in the lcl xml files.


>[...]


Mattias