buttonsrtoys buttonsrtoys - 11 months ago 43
C++ Question

Does commenting variables inline with Doxygen come with any penalties?

I see most Doxygen docs for commenting c++ functions looking something akin to

/// a description of the function or method followed with comments, like so
/// @return true=success, false=error
/// @param[in] bar blah blah
/// @param[out] baz blah blah
/// @param[out] quux blah blah
/// @param[out] quuux blah blah
/// @param[out] quuuux blah blah
static bool foo_one( int *bar, int *baz, int *quux, int *quuux, int *quuuux );

or the xml equivalent (roughly)

/// a description of the function or method, followed by
/// <returns>true=success, false=error</returns>
/// <param name=bar>blah blah</param>
/// <param name=baz>blah blah</param>
/// <param name=quux>blah blah</param>
/// <param name=quuux>blah blah</param>
/// <param name=quuuux>blah blah</param>
static bool foo_two( int *bar, int *baz, int *quux, int *quuux, int *quuuux );

but I've been mostly commenting my parameters inline, like so

/// a description of the function or method, followed by
/// @return true=success, false=error
static bool foo_three(
int *bar, ///< [in] blah blah
int *baz, ///< [out] blah blah
int *quux, ///< [out] blah blah
int *quuux, ///< [out] blah blah
int *quuuux ///< [out] blah blah

All three of these give identical output in the html file (with the exception of the middle one, which doesn't specify in/out).

My question: Are there features of Doxygen, Visual Studio, or any other environment that I won't be able to utilize with my inline approach? I understand that there are personal preferences when writing and reading the comments in code itself and would prefer not to debate those. I'm only interest in know if there are Doxygen or other environment features or formatting I'll be missing out on.



Doxygen itself will work just fine with inline comments.

However, also consider the effect on history recorded by the source code control system (for example, git, and git blame)

With inline comments, the last person who changed the line is whoever added or changed documentation, which makes it harder to find when / why the code itself was changed.

With comments on separate lines, especially if documentation is added after the code, inspecting history to find code changes is easier.