[pacman-dev] [PATCH 1/3] alpm.h: add Doxygen-style doc to package-related functions.

[Rémy Oudompheng]

On 2011/3/2 Dan McGee <dpmcgee at gmail.com> wrote:
> We will come across it moving on, but we should also pick a format we
> plan to follow, as I've seen several:
> 1) Put first line on /** line, everything else follows after a
> newline. This is the most compact.
> 2) Same, but newline and empty line after first line.
> 3) Use @brief, then a empty line, then remaining text. Things also
> seem to have spaces between every part (brief, summary, params).
> 4) Compact but using @brief.
>
> I don't care- as I said, I'm letting you call the shots, but we should
> try and pick one and stick with it and eventually retrofit everything
> to work this way.

I vote for compactness (at least in .h files). So I'd say my preferred
formatting is

/** @brief Some description.
 *
 * @params param a parameter.
 * @return the result
 */

and when the description is verbose (like for the description of the
confusing return types between depends, optdepends, replaces...)


/** @brief Some description.
 *
 * A verbose explanation.
 *
 * @params param a parameter.
 * @return the result
 */