[Lazarus] Documentation contribution

[Hans-Peter Diettrich]

Felipe Monteiro de Carvalho schrieb:
> On Fri, Feb 10, 2012 at 12:32 PM, Hans-Peter Diettrich
> <DrDiettrich1 at aol.com> wrote:
>> Again I found almost all of my notes removed from the LCL documentation. If
>> this is how my work is honored, I see no reason why I should spend any more
>> time with contributing to the Lazarus documentation :-(
> 
> I removed them:
> 
> http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=rev&root=lazarus&revision=35270
> 
> Sorry if you take it so badly, but I had already previously opened a
> topic to talk about that and you ignored it apparently.

I only remember that you stated that you don't like such notes.

> I remain with
> the oppinion that things like:
> 
> <descr>implement in descendants [what?]
> 
> Are not acceptable in our documentation.

Such an entry is absolutely useless without instructions *what* should 
be implemented at all. If you can't see that yourself, then you better 
keep your hands off the documentation.


> If you want to keep notes
> about things that you see in the documentation, then maybe you should
> create a separate file: lazarus/docs/xml/hans_peter_notes.txt and
> write there:
> 
> LCL.Controls.TControl.DoOnParentHandleDestruction -> what?
> 
> So that people that building the CHM and press F1 don't have to read "[what?]"

You seem not very familiar with writing documentation?
Notes are ignored unless brought into sight every now and then. Did you 
e.g. read StyleGuide.txt?


> Also, many of your notes are plainly wrong, for example lclintf line 83
> 
> <p>[this looks outdated?]
> 
> It is not outdated.

Thanks for confirming your ignorance :-(

 >>
@@ -81,7 +80,7 @@
          <short>Draws an elliptical curve.</short>
          <descr>
            <p>Use Arc to draw an elliptically curved line with the 
current Pen.</p>
-          <p>[this looks outdated?]
+          <p>
              The angles angle1 and angle2 are 1/16th of a degree. For 
example, a full
              circle equals 5760 (16*360). Positive values of Angle and 
AngleLength mean
              counter-clockwise while negative values mean clockwise 
direction.
<<

If you had taken a look at Arc(), you certainly had noticed that the 
parameters "angle1" and "angle2" do not exist any more. Do you need 
better glasses?


> Also in lclintf line 2637:
> 
>  <!-- does not apply[?]	
> 2640	   StartIndex gives the index of the first point in the array to

The same here: Where can you find an "StartIndex" parameter???

> Yes, it does apply. You wrongly commented out correct documentation so
> I fixed it.

Do we document *existing* code, or write science-fiction?

> I addressed a majority of the valid comments, the main missing thing
> being the screen/client mouse coordinates. Indeed one would need to
> check those.

You better stay away from comments which you don't understand, and leave 
it to people with better understanding of the matter to make 
*appropriate* corrections.


Sorry for my harsh wording, but your "corrections" exceed my frustration 
tolerance :-(

DoDi