[Lazarus] Documentation and Help for Lazarus (content)

[Martin]

Chris Kirkpatrick wrote:
>
>
> 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.
I only starting looking at the help again when this thread came up. when 
I was new to lazarus (less than a year), I gave it a try, and I must 
have ended up a couple of times on docs that didn't help me (and back 
then I did probably not explore the "See also" link. I just thought: ok, 
new usable help, never mind.
That is why I pointed this out.

In fact before I send the mail, I had a draft, where I had nearly 
rewritten the base-help of Notification, before I discovered it. Once 
you know that, there is indeed a lot of help available.

>
> 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.
I think it is not only he wording:  "calls inherited" to me is useless, 
since it is no more than the pascal code reads. "calls inherited so 
inherited can do...." better. IMHO writing it in more natural language 
"passing the information/message/signal on to it's parent, so ..." makes 
it more readable.
( we were recently told that programmers are users too  .... SCNR ;-> )

The essential is IMHO and as I said, to answer the first curiosity on 
the first page, which no need to click any link.it is the answer to a at 
least one of the question:
- Why is this called (in the example, why is the action list removed)
- When/Where is this called
In most cases at least one of the 2 (or both) should be present, even if 
it is just a short sentence. The details can be on a link (maybe the see 
also can be local attached to the sentence)

then of course the:
- What does it question.
This is already covered (in the example it already said, it removes the 
action-list).

> 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'.
True, that's why I gave an example. I didn't re-explain the full: it 
need to be registered by FreeNotification or to be owned.....

Notification can be used for a lot of different things, if a user wants 
to user it on it's own.
In the IDE it is used for a few different causes too.

The main one is that a child, or linked control is destroyed

There are 2 main reason why someone may have pressed help for it
1) they see it being used, and need to know what it does
2) They seek a function doing something, and need to find out if this is 
the one.

1) the first is answered (imho) by my example
" Called to notify the Form  that another control has been destroyed (or 
otherwise removed). "
which is the main difference to the existing entry.

2) requires the full context from the base class and probably even examples.
So it cannot be repeated in every class.

>
> 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.
>
I agree with you it may be could to put some more info (maybe a copy) 
into the visible components T(Cutom)Form class. Those 2 should ideally 
have a combined help entry. Well for Notifiaction they will have that. 
For the properties, that are in TForm's published section, I do not know 
if it is possible.
> Anyone with ideas for improvement is free to post a message, or even 
> better, submit a patch for improved documentation.

I know...


Best Regards
Martin