Do comments have variables built into Doxygen with any penalties?

Question

I see most Doxygen docs for commenting out C ++ functions that look like something similar 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 xml equivalent (approximately)

 /// 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 basically commented on my inline options, 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 them give identical output in the html file (except for the average, which is not specified in / out).

My question is: Are there any functions of Doxygen, Visual Studio or any other environment that I can not use with the built-in approach? I understand that there are personal preferences when writing and reading comments in the code itself and prefer not to discuss them. I'm just curious to know if there are any Doxygen or other environment features or formatting that I am missing.

Answer 1

Yes.

Doxygen itself will work great with inline comments.

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

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

With comments on individual lines, especially if documentation is added after adding code, it is easier to check the history of code changes.