[Lazarus] Documentation contribution

[Hans-Peter Diettrich]

Felipe Monteiro de Carvalho schrieb:
> On Fri, Feb 10, 2012 at 8:24 PM, Hans-Peter Diettrich
> <DrDiettrich1 at aol.com> wrote:
>> I only remember that you stated that you don't like such notes.
> 
> It is not about liking, I think it is just plainly obvious that if
> someone downloads our software and builds our docs, presses F1 and
> reads [really?] it makes us look ridiculous so it is not acceptable to
> have that in our documentation.

You seem to prefer the Delphi way, where no reasonable help has been 
provided in the last decade, while the help system was changed from 
WinHelp to HtmlHelp?

That's a reasonable decision, but at least Delphi/RadStudio offered to 
download and use the fine D7 help even for the new versions.

My viewpoint is different, I would never start using a product where I 
found the documenation incomplete or wrong. That's why I started to fill 
the gaps in the existing documentation, and to point to all those places 
where I could not find out the truth myself.


>> 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.
> 
> It doesn't matter if it wasnt good before. Your [?] tags make it worse.

They are *intended* to make it *so* worse, that the gurus (Lazarus team) 
finally decide to contribute the required documentation, instead of only 
inventing new features :-]

As a doctor would say: cure the disease, not only the symptoms.


Just another idea: Can't we delay a solution to the next release?
Then we can have the annotated documentation in the trunk, and a 
finalized version in the release branch.


I didn't want to go into details now, but the following is a good 
example of essential differences between Lazarus versions:

> function Arc(DC: HDC; Left,Top,Right,Bottom,Angle16Deg,
> Angle16DegLength: Integer): Boolean; {$IFDEF
> IF_BASE_MEMBER}virtual;{$ENDIF}
> 
> Then just change it to Angle16Deg and Angle16DegLength.

In this case it might be sufficient to only rename the parameters. Other 
drawing functions have changed from/between angles (as above) and arc 
coordinates, with both versions available in TCanvas.Arc (unit Graphics).

> From reading
> "looks outdated" how am I supposed to know that you mean that the
> parameter name is slightlt wrong?

I spent much time in updating the docs to the current LCL code, removing 
old and inserting new parameters. When I came across such changes, I 
considered it a reason for a review of these procedures, to exclude or 
mention possibly more changes.

If I had found the description more than only *possibly* outdated, I had 
replaced it immediately, without adding a revision note.


Ah, another idea: can we leave revision notes in the docs, as invisible 
comments, to indicate when an issue has been revised?

This would require to edit the XML sources directly, what was impossible 
when I revised the documentation for the first time, using LazDE or 
FPDoc Editor. It also would require to verify that no tool removes XML 
comments - here I'm not so sure about LazDE, which heavily reformats the 
raw (unindented) XML files.


> As far as I remember I wrote this
> documentation, and it is not outdated, I just made a copy+paste error
> in the parameter name because the function is nearly identical to its
> twin sister from TCanvas and I was documenting both at the same time.

I'm normally very careful when touching other people's texts, that's why 
in this particular case I left the original content in the file, and 
only turned the suspect part in an comment. Aren't we *both* right in 
our assumptions, that the Arc description was (slightly) outdated, but 
was still valid except for the changed parameter names?
Peace? ;-)

In other (more obvious) cases I removed real crap immediately, and 
replaced it by more up-to-date descriptions, as far this was possible 
from the source code. In the case of *abstract* methods it is impossible 
to find out anything about the purpose and inteded implementation of a 
method, due to inexistent source code. I agree that [what?] is not 
always easily understandable, but it should be considered a *strong* 
invitation to the inventors of that method, to supply the missing and 
required information.

Next time I'll try to be more precise, using something like
   [what should the method do in derived classes?]
And I would be happy if such notes are not simply removed. When somebody 
had a look at a note, he may turn it into an XML comment, telling other 
contributors that the content was revised accordingly, and now is in 
more correct or complete state. These comments find their way into the 
repository, at least, even if later on some tool or the author of the 
note may decide to remove them entirely (as resolved).

What do you think about this idea, and those mentioned above?

DoDi