At Sat, 12 May 2018 23:05:03 -0700 Greg Ercolano <e...@seriss.com> 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
> Doxygen-users@lists.sourceforge.net
> 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
hel...@deepsoft.com -- Webhosting Services
------------------------------------------------------------------------------
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
