Julian Foad wrote:
> Examples:
> /** One-line comment. */
> #define GLOBAL_MACRO BLAH
>
> /** More than one
> * line. */
> typedef struct foo foo;
>
> /** More than one
> * line.
> */
> struct foo {
> int member; /**< Documentation of this member. */
> }
If we document these, I'd only allow these two forms:
/** One line (brief) comment. */
and
/**
* Brief description.
* Optional longer description.
*/
That is, the /** and */ in multiline comments should be on a line by
themselves. That way the text alignmebt is nicer, and multiline comments
more visible. This applies to most of your examples, so I won't repeat
it later on.
> Do not use words like "above" and "below" to reference other APIs.
> Reason: The documentation may be laid out differently from the source
> files.
Yup, use doxygen's links instead.
> Surround pre-formatted text, whose horizontal and vertical spacing is
> to be preserved, by "<pre>...</pre>", or by "<code>...</code>" if it
> is C source code. This should only be used where necessary, and
> should not detract unduly from the presentation in the header files
> themselves. It should not be used on plain text paragraphs like notes
> and warnings.
Nope, if it's code it should be between @code and @endcode, like so:
/**
* Transmogrify the xylph in @a nadger.
* The lifetime of the returned zobkin is controlled by
* metamorphing the @a fondal; for example:
* @code
* fondal = meta(morph, global_fondal);
* zobkin = transmogrify(get_default_xylph(), fondal);
* @endcode
*/
Other preformatted text should be enclosed in @verbatim and
@endverbatim. Using the latest version of doxygen, you almost never need
HTML tags any more.
> 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.
> [UNSURE. UNIMPORTANT.]
> Use the plain English words "true", "false" and "null" rather than
> upper case or marked up versions like "TRUE", "@c NULL", etc.
> Reasons: The TRUE, FALSE and NULL macros are so common that there is
> no need for every interface that uses them to link to them, nor to
> remind the reader that these are the particular macro names we use to
> represent truth and falsehood and null pointers.
> Example:
> If @a prompt is true, return null.
> @a string may be null, in which case set @a *found to false.
+1
> DOXYGEN USAGE POLICY: SYMBOL REFERENCES (LINKS AND QUOTING)
>
> Refer to an argument of the current function with "@a". The
> documentation writer may, but need not, treat the name of the argument
> as a word in the sentence. (Sometimes it is very convenient to do
> so.) The "@a" is never considered to be a word in the sentence; it is
> absent from the Doxygen output.
> Examples:
> Print the string @a string.
> Print a @a string.
It's interesting to note that Doxygen treats @a strictly as a formatting
directive; i.e., it won't associate the names tagged with @a with
function parameters. That's a pity, because we can't get warnings about
misspellings or missing argument documentation.
> The members of a structure, enumeration, etc. should have their own
> documentation comments, but if they are documented within the
> container's comment, then refer to them with "@a ...".
> Reasons: In terms of documentation, a member of a structure is very
> similar to an argument of a function.
> Alternatives: "@c".
I think @a is correct here, given the context. @c is for constants.
> [UNSURE.]
> Refer to an argument of a different function with prefix "@a ".
> Reason: "@a" doesn't actually mark the item as an argument, it just
> marks it in a particular font, so using "@a" for all arguments makes
> sense.
> Note: I'm not sure I agree with this. I'd also be happy to have them
> quoted differently, e.g. with "@c" or with quotation marks.
> Examples:
> Pass @a input straight on to the @a receive parameter of
> svn_other_function().
I guess this is consistent.
> Refer to any function with suffix "()", and not with prefix "@c".
> Reasons: It looks good in the source text. Doxygen makes it into a
> link automatically if it is a documented symbol, and if not, it still
> looks good in the output.
> Examples:
> Like svn_error_create() but uses printf().
+1
> [UNSURE.]
> Refer to a Subversion public structure with just its name (not with
> "@c"). Refer to a member of one with "struct_name::member_name".
> Reasons: Doxygen treats a structure as a class, and so regards it as
> a primary type, and always makes it into a link if it is a documented
> symbol.
> Alternatives: Prefix "#" or "::", and/or "@c".
> Examples:
> svn_string_t
> svn_opt_revision_t::kind
Certainly not @c. We should let Doxygen generate links wherever
possible. '#' is for macros, not types.
> 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").
> Reasons: It generates a link, and it is neater in the source than
> "@c". Enumerated constants are excluded because Doxygen considers them
> to be in their own namespaces, not global.
> Alternatives: prefix "::".
> Examples:
> #svn_revnum_t
> #SVN_INVALID_REVNUM
+1
> Quote any other symbol (e.g. APR symbol, enumerated constant, literal)
> with "@c ..." for a single word or "<tt>...</tt>" for multiple words.
Ah, i hate the <tt> bit...but I can't think of an alternative. @verbatim
is multiline, unfortunately...
> Reason: These are not references, and just need to be written in a
> distinctive font, which is what "@c" and it multi-word equivalent
> "<tt>" do.
> Examples:
> @c NULL
> @c SVN_ERR_CANCELLED
> @c int
> <tt>const char *</tt>
> @c apr_hash_t
> <tt>apr_hash_t *</tt>
> <tt>#svn_string_t *</tt>
> <tt>/dev/null</tt>
>
> [SIMPLER: Instead of the last three rules (svn_struct, #svn_other, @c
> non-svn), perhaps just the following:]
> Quote any non-function symbol or literal with "@c name" or "<tt>naming
> words</tt>".
> Reasons: Simple rule. It is what we are doing already. Generates a
> cross-reference only for structures, but that may be good enough for now.
-1. The links are extremely useful.
>The "Modules" list (from "@defgroup") is very poor.
>
>
Yup. Usage of @defgroup and @ingrouop is another thing we should set a
policy on and document.
>Ensure that every hash has its key and value types documented. (This is not a Doxygen issue.)
>
>
+1
>Ensure that "Similar to" and "Same as" and "Like" are followed by a cross-reference.
>
>
Ah, @see :)
>Rare use of @copydoc, @em, @name, @see. Maybe eliminate or use more widely?
>
>
"Similar to foo()" is @see foo()
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Apr 8 01:49:35 2005