[Lazarus] Documentation rev33561

[Hans-Peter Diettrich]

Felipe Monteiro de Carvalho schrieb:
> 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.

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.

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

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