Thanks for the review, Branko. I'll incorporate your feedback in the second
draft. Comments on a few of your points:
Branko Čibej wrote:
> Other preformatted text should be enclosed in @verbatim and
> @endverbatim. Using the latest version of doxygen, you almost never need
> HTML tags any more.
Good. I'll read up on that.
> Julian Foad wrote:
>> A note or warning should be a paragraph starting with "@note" or
>> "@warning", not "NOTE:", etc. If the source code needs attention
>> (e.g. is buggy) then use a "###" attention marker as well.
>
> What, in the API docs? No way. If we have such a bug that it's necessary
> to say so in the API documentation, use @bug or @todo. Doxygen will
> generate a separate list of such items.
I'll review the existing "###" comments (about 35 of them) and see what's best
for them.
>> [UNSURE.]
>> Refer to a Subversion public structure with just its name (not with
>> "@c").
[...]
>> Alternatives: Prefix "#" or "::", and/or "@c".
[...]
> Certainly not @c. We should let Doxygen generate links wherever
> possible. '#' is for macros, not types.
According to the manual on www.doxygen.org, '#' can mark any symbol, and is
almost identical to a '::' prefix. Not that we would necessarily want to use
it that freely. The manual doesn't seem to make any recommendations about best
usage - it only documents the syntax.
>> Refer to any other Subversion public symbol in the global namespace
>> (e.g. typedef, #define macro, but not enumerated constants) with
>> prefix "#" (not with "@c").
>
> +1
You contradict yourself here. How would you prefer to mark types that aren't
structures?
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Apr 8 15:19:18 2005