[Lazarus] Documentation style

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

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

Sounds good.


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

Who can know that for sure?


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

A description without duplication of the name. The need for a different 
description can remove mental barriers, which otherwise can cause 
repetition of the obvious.


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

Yes, I suggested that as a workaround. But the short description is not 
editable in that page. I prefer to have the long description visible 
while coding, and when I want to insert a missing (short) description, I 
have to switch pages.


>> [...] 
>> The same for parameters, whose separate descriptions are not normally 
>> accessible in e.g. the FPDoc editor.
> 
> ToDo. Please create a feature request.

Okay.


>> [...]
>> As already mentioned in another mail, all links to #LCL are broken now. 
> 
> I changed the #LCL to #LCLBase in the lcl xml files.

Argh :-(

DoDi