-Wdocumentation thinks gtk-doc is doxygen, generates false positives

[Quuxplusone]

Bugzilla Link	PR17291
Status	NEW
Importance	P normal
Reported by	Sean McBride (sean@rogue-research.com)
Reported on	2013-09-19 14:24:16 -0700
Last modified on	2021-11-09 10:20:36 -0800
Version	trunk
Hardware	Macintosh MacOS X
CC	aaronpuchert@alice-dsl.net, dgregor@apple.com, egall@gwmail.gwu.edu, gribozavr@gmail.com, llvm-bugs@lists.llvm.org, llvm-dev@redking.me.uk, neeilans@live.com, richard-llvm@metafoo.co.uk
Fixed by commit(s)
Attachments
Blocks
Blocked by
See also	PR19581, PR17437, PR17348, PR16713, PR31037, PR16092, PR29156

gtk-doc is a kind of markup similar to doxygen:
http://www.gtk.org/gtk-doc/

When clang's -Wdocumentation encounters this, it (sometimes?) misinterprets it
as doxygen and thus gives false positive warnings.

In my case, I see this building VTK.  VTK mostly uses doxygen, but has some
third party code (libxml2) that uses gtk-doc, and I see warnings like below.

It would be nice if clang could distinguish, since I want -Wdocumentation
enabled since the project mostly uses doxygen.

----------------------------
In file included from
/Users/builder/external/VTK/IO/Infovis/vtkXMLTreeReader.cxx:34:
In file included from /Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/parser.h:16:
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/tree.h:527:4: warning: unknown
command tag name [-Wdocumentation-unknown-command]
 * @ctxt:  a DOM wrapper context
   ^
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/tree.h:528:4: warning: unknown
command tag name 'node'; did you mean 'note'? [-Wdocumentation]
 * @node:  the context node (element or attribute)
   ^~~~~
    note
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/tree.h:529:4: warning: unknown
command tag name [-Wdocumentation-unknown-command]
 * @nsName:  the requested namespace name
   ^
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/tree.h:530:4: warning: unknown
command tag name [-Wdocumentation-unknown-command]
 * @nsPrefix:  the requested namespace prefix
   ^
In file included from
/Users/builder/external/VTK/IO/Infovis/vtkXMLTreeReader.cxx:34:
In file included from /Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/parser.h:18:
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/hash.h:64:4: warning: unknown
command tag name [-Wdocumentation-unknown-command]
 * @payload:  the data in the hash
   ^
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/hash.h:83:4: warning: unknown
command tag name 'data'; did you mean 'date'? [-Wdocumentation]
 * @data:  extra scannner data
   ^~~~~
    date
/Users/builder/external/VTK-torture-clang-dbg-
x86_64/ThirdParty/libxml2/vtklibxml2/libxml/hash.h:92:4: warning: unknown
command tag name 'data'; did you mean 'date'? [-Wdocumentation]
 * @data:  extra scannner data
   ^~~~~
    date

----------------------------

[Quuxplusone]

These two syntaxes are very similar. Fortunately, there is a colon after the parameter name, and we could interpret "@foo:" as a parameter reference instead of a command.

So, this particular issue can be theoretically fixed. Are there any other incompatibilities that cause us to produce warnings?

[Quuxplusone]

Dmitri, the most common is definitely the "@foo:" type. There may be others, but it's hard to see through the noise, ex, see my VTK buildbot submission here:

http://open.cdash.org/viewBuildError.php?type=1&buildid=3034253

I think the only other -Wdocumentation bug I know of is #16713.

[Quuxplusone]

In my humble opinion, this should be considered a release blocker for 3.4. False positive warnings are very annoying, and -Wdocumentation has a few of them.

[Quuxplusone]

(In reply to comment #3)
> In my humble opinion, this should be considered a release blocker for 3.4.

I'd agree with this, except 3.4 has already been released, and I'm still
running into it with 3.5...

[Quuxplusone]

Just a note: this still repros with clang r287114 (today's trunk).

Here is an actual test case:

---test.cxx--------------------
/**
 * xmlDOMWrapAcquireNsFunction:
 * @ctxt:  a DOM wrapper context
 * @node:  the context node (element or attribute)
 * @nsName:  the requested namespace name
 * @nsPrefix:  the requested namespace prefix
 *
 * A function called to acquire namespaces (xmlNs) from the wrapper.
 *
 * Returns an xmlNsPtr or NULL in case of an error.
 */
typedef int (*xmlDOMWrapAcquireNsFunction) (int ctxt,
                                            int node,
                                            const int *nsName,
                                            const int *nsPrefix);
-------------------------------

clang -fsyntax-only -Weverything test.cxx

gives:

test.cxx:3:4: warning: unknown command tag name [-Wdocumentation-unknown-
command]
 * @ctxt:  a DOM wrapper context
   ^~~~~
test.cxx:4:4: warning: unknown command tag name [-Wdocumentation-unknown-
command]
 * @node:  the context node (element or attribute)
   ^~~~~
test.cxx:5:4: warning: unknown command tag name [-Wdocumentation-unknown-
command]
 * @nsName:  the requested namespace name
   ^~~~~~~
test.cxx:6:4: warning: unknown command tag name [-Wdocumentation-unknown-
command]
 * @nsPrefix:  the requested namespace prefix
   ^~~~~~~~~

[Quuxplusone]

FYI: still reproduces with today's clang:
clang version 6.0.0 (trunk 314864) (llvm/trunk 314863)

[Quuxplusone]

Just a note to say it still reproduces in trunk 347180.

[Quuxplusone]

Current compiler warning: https://godbolt.org/z/iYQ4Wp