Felipe Monteiro de Carvalho schrieb:
On Fri, Feb 10, 2012 at 8:24 PM, Hans-Peter Diettrich
<[email protected]> 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
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
