Re: [Doxygen-users] doxygen commenting with //!< not working for last parameter of C++ methods

[Greg E. <er...@se...>]

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.