[Lazarus] Documentation rev33561

[Felipe Monteiro de Carvalho]

On Thu, Nov 17, 2011 at 1:50 AM, Hans-Peter Diettrich
<DrDiettrich1 at aol.com> wrote:
> Right, the links should be supplied. I've left that for later, because
> this job can be done by everybody, with no detailed knowledge of the
> methods themselves.

But the links were already there. My whole point is that you removed
information. You should correct it entirely, not leave half-done for
an unknown future. We don't have full time employess to finish it
later on.

You really need to do each correct as if it was permanent, never leave
things for other people to finish later on.

If necessary do it slower, speed is not a requirement, but fixing
regressions is a requirement. And your commits caused documentation
regressions, please fix them.

> I've removed many descriptions on overridden methods, because these
> should use the same (basic) descriptions, so that errors can be
> corrected in one single place.

This part is correct, the wrong part is doing it only half-way and not
providing the correct links which were already there (aka you don't
even needed to search to figure out what were the adequate links).

> The [?] marks items which deserve confirmation or *reasonable*
> documentation, which cannot be derived from the implementation. Only the
> *inventors* of the methods can provide that missing information.

AFAIK That's unacceptable. The documentation in trunk is not a sketch.
We do not have full time personal to review your sketch and finish it.
And we cannot ship documentation with such descriptions and expect to
be taken seriously. If I saw such documentation in a project I would
seriously doubt that this framework is usable.

If you don't know what a method does, don't change it's description,
but don't put [?] in the documentation and also don't write that you
don't know what something does.

> Above is an example of *very bad* documentation, that is far away from
> reality. I had to remove many such wrong descriptions from the
> documentation :-(

It was bad, but your new description is even worse, I consider it a
regression. I already supplied a new version, please apply it and also
clean or revert all places where [?] as documentation exists.

-- 
Felipe Monteiro de Carvalho