Hello,

It seams that some items lost information:

<element name="TCustomFrame.GetControlClassDefaultSize"> <short>
<var>GetControlClassDefaultSize</var> - returns its own defaults for frame design, overriding the inherited values</short> <descr/>
<errors/>
<seealso>
<link
id="#LCL.Controls.TControl.GetControlClassDefaultSize">TControl.GetControlClassDefaultSize</link> </seealso>
</element>

Was changed to:

<element name="TCustomFrame.GetControlClassDefaultSize"/>

Which misses the link, it should probably be changed into a direct link.

In many places this has happened, they should probably all be changed into direct links.

Also:

2173 <element name="TCustomForm.ActiveChanged"> <element name="TCustomForm.ActiveChanged">
2174 <short> <short>[?] Does nothing. 2175 <var>ActiveChanged</var> - method for a form that is active and changed</short> </short>
2176 <descr/> <descr/>
2177 <errors/> <errors/>
2178 <seealso/> <seealso/>
2179 </element> </element>
2180 <!-- procedure Visibility: protected --> <!-- procedure Visibility: protected -->

Please never document something as "[?] Does nothing."

Felipe Monteiro de Carvalho wrote

Please never document something as "[?] Does nothing."

Just to add on that, I think it would read much better like this:

This method is provided for descendent classes so that they may override it and do something when the active state of the form changes. In TCustomForm it does not do anything by design.

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.

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.

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.

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 :-(

When I did a Google search on e.g. WantChildKey, I came across an thread in some eastern Europe language. But Google says that the original language is English, and consequently could not translate the articles :-(

DoDi

I'd prefer:

This method is called [when?]
It can be overridden [to do what?]

With the placeholders filled in with *reliable* and *useful* information. It should be obvious that virtual methods are designed for being overridden in derived classes. But he who overrides such a method *must* know about the purpose of the method, else nobody can ever override it in a meaningful way.

DoDi

Hans-Peter Diettrich 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 wrote

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.

I have to agree with Felipe here. Seeing [?] inside the documentation itself does give the documentation a "bad smell". Why not simply use the comment tags [eg: <!-- my comment here -->] inside the XML files. That way it doesn't appear inside the documentation context, but the XML is searchable to find areas that need to be addressed by somebody else.

Documentation is not winning an price for beauty, but for correctness and usability. If you don't like the [?] marks, then start replacing them by the missing information.

DoDi

Hans-Peter Diettrich wrote

Documentation is not winning an price for beauty, but for correctness and usability.

"[?] Does nothing." is neither correct nor useful.

If you don't like the [?] marks, then start replacing them by the missing information.

That's not a valid argument, they aren't there since day 1, you put them there. Everyone commiting to the lazarus subversion has only 1 responsability: to fix regressions that he causes. And as I explained you are generating documentation regressions.

Is it too much to ask?

I don't make such a big deal when I generate problems, I simply fix them. Generating problems is a normal part of development, but I don't understand why you refuse to fix the problems which you created.

Right, I put them in as ToDo marks.

WRT to documentation it looks to me that any question is too much. Look at my recent posts, and at the (missing) answers :-(

I don't make such a big deal when I generate problems, I simply fix them. Generating problems is a normal part of development, but I don't understand why you refuse to fix the problems which you created.

In "normal" development everybody can create an bug report, when he finds an error or regression, and wait until it is fixed. When you tell me the exact places where you found regressions, these will move to the top of my ToDo list.

DoDi