[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Doxygen policy ideas

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2005-04-08 15:17:37 CEST

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

This is an archived mail posted to the Subversion Dev mailing list.