[Lazarus] Documentation style

[Martin]

On 23/07/2011 16:06, Jürgen Hestermann wrote:
> Mattias Gaertner schrieb:
> >> Then no extra documentation is needed.[...]
> > How to distinguish an item that needs documentation and an
> > item that does not need documentation?
>
> Well, if the current documentation just repeats the name (with 
> fillwords) then it is useless IMO and should be deleted. 

True and yet not...
Sure there is no point in having documentation, that is empty...

Removing empty documentation means work. It has to be ensured, that not 
accidentally real docs are also affected. It needs to be merged and 
commited...
This work ends up with the developers who have to commit. (Even if 
provided as patch, by someone else). So unless there is real value from 
removing it, it may as well be left as it is.

One might argue, that once removed, people can identify the missing 
bits, and contribute. Such promises exist plenty, and are rarely 
fulfilled. So again, unless someone who has proven himslef by providing 
patches containing real quality replacement docs; unless such a person, 
asks for it, saying it would help him to *continue* his proven efforts; 
unless such time, there is no point in removing them.


> But I didn't mean that in these cases documentation is not *needed*, 
> just the opposite. I think that all functions/methods/language 
> constructs/types/... should be documented. It's just that the 
> *current* documenation is often useless because of its simple name 
> repeat. The important information about side effects and internal 
> structure is missing often.