Page MenuHomePhabricator

[clang][doxygen] Fix -Wdocumentation warning for tag typedefs
ClosedPublic

Authored by jkorous on Feb 17 2020, 4:31 PM.

Details

Summary

For tag typedefs like this one:

/*!
@class Foo
*/
typedef class { } Foo;

clang with -Wdocumentation gives:

warning: '@class' command should not be used in a comment attached to a non-struct declaration [-Wdocumentation]

while doxygen seems fine with it.

There's @typedef command in doxygen but from the description its semantics seem different.
http://www.doxygen.nl/manual/commands.html#cmdtypedef
@struct and @class seem appropriate.
http://www.doxygen.nl/manual/commands.html#cmdstruct

rdar://problem/58960486

Diff Detail

Event Timeline

jkorous created this revision.Feb 17 2020, 4:31 PM

Apparently it's related to:

commit a433e7141fb3f697e6430437ee73b19076603c1b
Author: Sam McCall <sam.mccall@gmail.com>
Date:   Wed Nov 13 21:30:31 2019 +0100

    [AST] Attach comment in `/** doc */ typedef struct A {} B` to B as well as A.

...adding clangd folks.

sammccall accepted this revision.Feb 20 2020, 7:07 AM

Thanks for fixing this!

clang/lib/AST/CommentSema.cpp
942

nit: dyn_cast_or_null on the next line and delete this?

972

nit: TypedefDecl (caps) and below

This revision is now accepted and ready to land.Feb 20 2020, 7:07 AM
vsapsai added inline comments.Feb 20 2020, 11:08 AM
clang/test/Sema/warn-documentation-tag-typedef.cpp
14

I'm thinking about also testing non-anonymous structs like

typedef struct Bar { } Bar;

But maybe it's not different enough or already tested.

Another idea which is out of scope of this change is to test name mismatch in case clang warns about it. Something like

/*! 
@struct Abc
*/
typedef struct { } Xyz;
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptFeb 20 2020, 11:33 AM
Herald added a subscriber: cfe-commits. · View Herald Transcript

@vsapsai Sorry! I read your comment only after landing this.

I reported this issue back in November, as https://bugs.llvm.org/show_bug.cgi?id=44143. This change fixes the bug -- I'll mark it as such.