Need a clearer strategy for unused args and doxygen

[Kurt Schwehr]

It's great to have doxygen comments and to have -Wdocumentation checking the args. However, the solutions for handling unused vars are not great.

This is just weird and it's no fun that it takes 4 lines:

/* end doxygen comments. */

/**/
/**/

void MyFunc( int /* nUnused */ ) {}

And having the arg flagged with CPL_UNUSED: cases where the var is actually used pass through without failing.

void MyFunc2( CPL_UNUSED int nUnused )
{
    return nUnused;  // Surprise, it really is used, but compiles.
}

Maybe a better solution would be something like:

#ifdef DOXYGEN_SKIP
/* Define for doxygen */
#define DOXYGEN_ONLY(x) (x)
#else
#define DOXYGEN_ONLY(x)
#endif
#define

void MyFunc( int DOXYGEN_ONLY(nUnused) ) {}

void MyFunc2( int DOXYGEN_ONLY(nUnused) )
{
    return nUnused;  // Compile will fail.
}

I would prefer something shorter than DOXYGEN_ONLY. Mabe DOC_ONLY (or DOX_ONLY)? So

#ifdef DOXYGEN_SKIP
/* Define for doxygen */
#define DOC_ONLY(x) (x)
#else
#define DOC_ONLY(x)
#endif
#define

void MyFunc( int DOC_ONLY(nUnused) ) {}

void MyFunc2( int DOC_ONLY(nUnused) )
{
    return nUnused;  // Compile will fail.
}

Or if we got really brave, just DOX?

#ifdef DOXYGEN_SKIP
#define DOX(x) (x)  /* Included just for Doxygen documentation. */
#else
#define DOX(x)
#endif
#define

void MyFunc( int DOX(nUnused) ) {}

void MyFunc2( int DOX(nUnused) )
{
    return nUnused;  // Compile will fail.
}

[Even Rouault]

This ticket has been automatically closed because Trac is no longer used for GDAL bug tracking, since the project has migrated to GitHub. If you believe this ticket is still valid, you may file it to ​https://github.com/OSGeo/gdal/issues if it is not already reported there.