doxygen \implements command and -Wdocumentation-unknown-command

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

doxygen \implements command and -Wdocumentation-unknown-command

Nicola Gigante
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?

Even if documentation typos on an external header are not a big issue, I’m trying to keep my project warning-free with -Weverything...

P.S. I’m using the clang shipped with the latest xcode

Bye,
Nicola
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: doxygen \implements command and -Wdocumentation-unknown-command

Dmitri Gribenko
On Fri, Mar 7, 2014 at 10:26 AM, Nicola Gigante
<[hidden email]> 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 <[hidden email]>*/

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: doxygen \implements command and -Wdocumentation-unknown-command

David Chisnall-4
On 7 Mar 2014, at 10:52, Dmitri Gribenko <[hidden email]> wrote:

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

This would make sense in Objective-C in the case of informal protocols.  They're less common now that formal protocols have optional methods, but they're still fairly widespread in older codebases...

David


_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev