Re: doxygen commenting with //!< not working for last parameter of C++ methods

At Sat, 12 May 2018 23:05:03 -0700 Greg Ercolano <[email protected]> wrote:

> 
> On 05/12/18 08:47, Richard Damon wrote:
> > On 5/11/18 2:44 PM, Greg Ercolano wrote:
> >>
> >>     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
> >> [..]
> >> string AskApp(const char *cmd,          //!< command to send app
> >>               const string& arg) {      //!< argument to command   <-- THIS DOESN'T WORK
> >>     if ( arg == "" ) {
> >> [..]
> >> __________________________________________________________________ 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'
> >> [..]
> >
> > 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.
> 
> 	Right, for sure it's the coding style, which indent(1)
> 	calls 'braces-on-func-def-line'.
> 
> 	I'd considered going with:
> 
> >> string AskApp(const char *cmd,          //!< command to send app
> >>               const string& arg         //!< argument to command
> >>              ) {
> >>     if ( arg == "" ) {
> 
> 	..which seems to work, but kinda defeats the purpose of the
> 	floating brace keeping the vertical size of the file small.
> 
> 	I decided to just stick with @param, and ensure the proper
> 	warning flags are enabled in Doxyfile.
> 
> > to place it in the right context. I personally use @param and look for
> > the warnings if things get out of sync.
> 
> 	Right, I'm of the same opinion.
> 
> 	It's too bad though; "//!<" is quite nice in that there's
> 	no way the names can get out of sync. It also removes the
> 	duplication of specifying the name twice; (once in docs,
> 	once in the code)
> 
> 	I'd log it as a bug, as I think doxygen should be able to
> 	cleverly handle different coding styles, but then there's this..
> 
> > 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.
> 
> 	Yes, it seems for instance even with '@param', if it appears after
> 	\returns, that changes the order. Huh.
> 
> 	And that pretty much puts to bed for me the idea of using '//!<'
> 	this way.. unless there's a way to force \returns to appear
> 	after params.
> 
> 	Thanks for the help -- wanted to make sure I wasn't missing something.

What does this produce:

/** This is my function
 *
 */
 
int myfunction (int universe, //!< This is the first argument
                int everything  //!< This is the second argument
                /**
                  * \returns An integer
                  */
                ) {
   return 42;
}

(Yes, this is probably really hokey...)



> 
> 
> ------------------------------------------------------------------------------
> 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
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
> 
>                                                                                                                             

-- 
Robert Heller             -- 978-544-6933
Deepwoods Software        -- Custom Software Services
http://www.deepsoft.com/  -- Linux Administration Services
[email protected]       -- Webhosting Services
                                                                                                         

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot