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.
------------------------------------------------------------------------------
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
