Martin schrieb:
On 15/02/2012 19:27, Mattias Gaertner wrote:
On Fri, 10 Feb 2012 14:52:13 +0100
Hans-Peter Diettrich<[email protected]> wrote:
[...]
IMO notes should not be hidden in comments. I want them displayed also
in the final docs - just as a reminder that some text is not reliable.
Reminders must be clearly marked. A simple [?] can be misleading.
And I would also cut that into 2 categories.
To me a simple Todo does not belong to the end user. (like "Need to
write an example", or "Review English grammar")
On the other hand, the following (in proper English) could be ok:
"This documentation is outdated, the parameters to the function have
changed." (give more info if avail)
I.e. you ask for perfectly formulated and clear comments *about* the
flaws in the existing documentation *only*, while the previously
existing documenation is accepted in any state (misleading, incomplete,
wrong...)???
Needless to say that I cannot share that VP. I don't want to write
another Ph.D. thesis about the docs. See also
http://en.wikipedia.org/wiki/Copy_editing
To add such notes, the reviewer must have at least enough understanding,
to be sure that something is wrong.
A simple "looks wrong to me" or "I don't get that at all" is not enough
to add a note.
What other solution do you suggest instead? Remove crappy or
questionable content, instead of only adding a note?
If we risk adding false notes (well it can always happen, but should be
as low risk as possible) then what good are the notes? You could not
trust them anyway.
I see an documentation review as an invitation to improve the existing
documentation. If some notes look too short or otherwise unclear,
everybody is free to ask the reviewer for a clarification. As long as
only I added [...] notes, it's clear who can answer related questions.
When an entry was found misleading or otherwise poor, in most cases
*not* the author of that part is capable or responsible for fixing it,
instead people with detailed knowledge about the *subject* or *language*
should put their hands on it.
We can always offer 2 (or more) versions of the help. With/Without notes
My intention was a feature in FPDoc, that allows to hide my notes, based
on the clear [...] syntax. The --emit-notes option perfectly reflects
that now, but only for an *out-of-line* <notes> section. A better
alternative could add an tag for *inline* comments, like the existing
<var> or <b> attribute tags. A <strikeout> attribute would come close to
my intention, to indicate both the range of the affected text, with a
note (attribute) inside the tag telling the reason why.
DoDi
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
