On 5/11/18 2:44 PM, Greg Ercolano wrote:
> I'm embarking on a C++ project, and want to get the doxygen comments
> right before the project gets too far along.
>
> I'd like to use //!< to comment the function/method parameters,
> but the coding style of the project seems to be causing trouble
> when it's used on the last argument:
>
> __________________________________________________________________ snip
>
> /// Send a message to main application asking for a result
> ///
> /// \returns a single string reply from the app.
> ///
> string AskApp(const char *cmd, //!< command to send app
> const string& arg) { //!< argument to command
> if ( arg == "" ) {
> ..stuff..
> }
> ..stuff..
> }
> __________________________________________________________________ snip
>
> It seems doxygen can't deal with this bracing style,
> with the opening brace being on the same line as the argument:
>
> warning: The following parameters of AddLetterDialog::AskApp(..) are not
> documented: parameter 'arg'
>
> I'll use @param if I have to, as I've used that on other projects
> that use this same bracing style (FLTK), but it's too easy for the
> @param comments to get out of sync with the code if the argument
> name changes. So //!< seems preferable. It also makes for less lines
> in the code.
>
> Is there a Doxyfile flag I'm missing for bracing style, or is this a bug?
>
> PS. Also, with the //!< comment style, for some reason doxygen is
> putting the parameters BELOW the return docs instead of above,
> which seems counter to convention.
>
My first guess is that the issue is the comment for the last argument is
no longer in the right context to refer to the argument, as it is no
long 'right after' the argument but is now inside the function.
You could try documenting with something like
const string& arg /**< arguement to command */ ){
or
const string& arg //!< argument to command
){
to place it in the right context. I personally use @param and look for
the warnings if things get out of sync.
As to the parameters coming after the returns, that is like because the
documentation is produced in the order it is in the file, (there is no
implicit sorting of these paragraphs) so since the parameters are
documented after the returns, that is how the documentation is produced.
--
Richard Damon
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
