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