[PATCH] D71966: [Wdocumentation][RFC] Improve identifier's of \param

[Mark de Wever via Phabricator via cfe-commits]

Mordante created this revision.
Mordante added reviewers: gribozavr2, juliehockett.
Mordante added a project: clang.
Herald added a subscriber: arphaman.

This fixes several issues with the processing of identifiers of a \param command:

**Like Doxygen allow multiple identifiers in one \param command **

For example:

/// \param foo, bar The description of foo and bar.
void fun(int foo, int bar);

Was interpreted as:

- a single identifier `foo,`
- a description of ` bar The description of foo and bar.`

It will now be interpreted as:

- two identifiers `foo` and `bar`
- a description of ` The description of foo and bar.`

Likewise:

/// \param foo,bar The description of foo and bar.
void fun(int foo, int bar);

Was interpreted as:

- a single identifier `foo,bar`
- a description of ` The description of foo and bar.`

It will now be interpreted as:

- two identifiers `foo` and `bar`
- a description of ` The description of foo and bar.`

**Improved identifier detection**

/// \param 42foo The description.
void fun(int foo);

The 42foo is not a valid identifier and will give a warning.

/// \param foo# The description.
void fun(int foo);

Will also trigger a warning since the identifier contains invalid characters.

**Improved typo correction of variadic arguments**

For example:

/// \param .. The description.
void fun(...);

Will suggest to change the identifier `..` to `...`. This will only happen if the function is variadic and the variadic argument has no documentation.

**Warn about undocumented function arguments**

If after the typo correction function arguments are not documented yet there will be a warning about these arguments. This only happens if at least one \param comment is used.

/// \param foo The description of foo and bar.
void fun(int foo, int bar);

This will warn about the undocumented bar.

/// fun's arguments are not documented
void fun(int foo, int bar);

This will /not/ warn about the undocumented foo and bar.

**Questions**

The undocumented function argument is part of -Wdocumentation. Should it remain here or be part of its own -Wdocumentation-undocumented-arguments?

The clang-doc has minimal changes to support the new feature. @juliehockett anything you want to improve. If so should these changes be in this patch or a follow-up patch?

**TODOs**

- The \tparam can be improved in a similar fashion. This will be done in a  separate patch.
- The identifier detection could try a bit harder to extract the identifier. It could detect and propose fixits for references, pointers, and arrays. For example it could offer a fixit for &*identifier[...]. This will be done in a separate patch.

Fixes PR14335: [-Wdocumentation] Multiple identifiers (comma,separated) are not recognized on \param


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D71966

Files:
  clang-tools-extra/clang-doc/Representation.h
  clang-tools-extra/clang-doc/Serialize.cpp
  clang/docs/ReleaseNotes.rst
  clang/include/clang-c/Documentation.h
  clang/include/clang/AST/Comment.h
  clang/include/clang/AST/CommentSema.h
  clang/include/clang/Basic/DiagnosticCommentKinds.td
  clang/lib/AST/Comment.cpp
  clang/lib/AST/CommentParser.cpp
  clang/lib/AST/CommentSema.cpp
  clang/lib/AST/JSONNodeDumper.cpp
  clang/lib/AST/TextNodeDumper.cpp
  clang/lib/Index/CommentToXML.cpp
  clang/test/AST/ast-dump-comment-json.cpp
  clang/test/AST/ast-dump-comment.cpp
  clang/test/Index/comment-to-html-xml-conversion.cpp
  clang/test/Index/overriding-ftemplate-comments.cpp
  clang/test/Index/overriding-method-comments.mm
  clang/test/Sema/warn-documentation-fixits.cpp
  clang/test/Sema/warn-documentation.cpp
  clang/tools/c-index-test/c-index-test.c
  clang/tools/libclang/CXComment.cpp
  clang/tools/libclang/libclang.exports

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D71966.235488.patch
Type: text/x-patch
Size: 140104 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20191228/15396741/attachment-0001.bin>