[Lazarus] Documentation and Help for Lazarus (content)

[Chris Kirkpatrick]

Martin wrote:
> Another thing about the help. And i feel bad about saying this, 
> because I really appreciate the effort that was made. And criticizing 
> it without having contributed seems all wrong.
> Never the mind, since we talk about it, I feel it should be mentioned
>
> Some of the documentation still reads like a mockup, providing not 
> more help than looking at the function itself.
>
Thank you for your comments: I take them very much to heart. I have been 
trying to get through most of the LCL classes, to produce at least SOME 
documentation, and I agree that much of it is very simplistic, but yours 
is probably the first useful feedback I have had, in several years of 
work, and I thank you especially for this.

As Waldo Kitty said in the next post, 'maybe someone who understands 
geek but doesn't speak geek should be involved to "average joe" the 
documentation'. I thought perhaps I was that average joe, being a 
retired physician rather than a programmer.

Part of the problem is that several of the methods involved are 
overridden at every level of inheritance: your example of Notification 
is a good one, as every class that uses it overrides the ancestor, and 
usually calls inherited Notification as part of its code. By the time 
you get to the classes that actually appear as widgets on a Form, there 
may be up to five or six levels of inheritance, each of which has added 
an override to the original description of the method. How much should I 
reiterate the information present in all the ancestors? I thought that 
was one of the reasons we used links and 'seealso'.

My proposal is that I concentrate on classes that are most immediately 
apparent to the user/application programmer, the ones represented by 
symbols in the component palette (or their immediate parent CustomXXXXX 
classes), and produce as full a description as possible, along the lines 
you suggest, even if it involves re-iterating some of the material from 
more primitive levels. So I shall concentrate first on overridden 
methods in StdCtrls, ComCtrls and ExtCtrls.

Anyone with ideas for improvement is free to post a message, or even 
better, submit a patch for improved documentation.

Regards - Chris