[cfe-dev] doxygen \implements command and -Wdocumentation-unknown-command

[Dmitri Gribenko]

On Fri, Mar 7, 2014 at 10:26 AM, Nicola Gigante
<nicola.gigante at gmail.com> wrote:
> Hello
>
> I’m including an header from a library (rapidjson, FWIW) and I get the “Unknown command tag name” warning on a
> snippet like this:
>
> /! C-runtime library allocator.
> /*! This class is just wrapper for standard C library memory routines.
>         \implements Allocator
> */
> class CrtAllocator {
> public:
>         static const bool kNeedFree = true;
>         void* Malloc(size_t size) { return malloc(size); }
>         void* Realloc(void* originalPtr, size_t originalSize, size_t newSize) { (void)originalSize; return realloc(originalPtr, newSize); }
>         static void Free(void *ptr) { free(ptr); }
> };
>
> I’m not up to date with doxygen, but it seems to me, by browsing the documentation, that the \implements command exists.
> Is this a false positive?

Hi Nicola,

On one hand, this is a valid Doxygen command indeed.

On the other hand, using it in C++ and Objective-C does not make much
sense for me, because the Doxygen manual describes the command
semantics like this:

> This command can be used to manually indicate an inheritance relation, when the programming language does not support this concept natively (e.g. C).

As you see, this command is specifically to mark *inheritance* (not
some abstract concept models), and only in languages that don't
support it natively.

I would say that this is indeed a bug, because we emit the wrong
warning.  The warning should say something like:

warning: class was marked as implementing 'Allocator', but it does not
inherit from it

... and it should be in a separate group so that projects that abuse
this command can turn it off.

On the second thought, this command might be useful to mark C++
template requirements satisfied by a type (CopyConstructible,
CopyAssignable, RandomAccessIterator etc.) while standard C++ still
does not have concepts.

+ Dimitri van Heesch

Dimitri, what is the intended usage of \implements in C++?  What is
your opinion on using it to mark template requirements satisfied by a
type?  If Clang starts checking that \implements matches the base
class list, then this use case could be broken.

I see two possible implementations of \implements in Clang:

* just accept anything;

* check that the classes are indeed in the base class list.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/