[Lazarus] Documentation contribution

[Martin]

On 10/02/2012 19:24, Hans-Peter Diettrich wrote:
>
>
>> 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?
>
Then we need to extend fpdoc. So we can build help (chm or other), with 
or without todo/notes

Yes it is true, everyone who wishes to write/contribute docs does need 
to see them. Even more: there is a need for an overview (like the todo 
list win for pascal todo)

But, any doc to the end user must not contain this.
It is useless, even irritating to the help seeking user

True the entry without the note is already of little, maybe even no use.
But a user seeking help, getting presented, with a out of context, 
single word question "What?" is worse. Remember the user does not know 
that this is a comment meant for the develeopper. The user assumes, that 
this "What" is some form of hint, that should help him understand the topic.


So we face the question what to do until such a todo-note feature exists.