[cfe-commits] r161261 - in /cfe/trunk: include/clang/AST/Comment.h include/clang/AST/CommentSema.h include/clang/Basic/DiagnosticCommentKinds.td lib/AST/Comment.cpp lib/AST/CommentSema.cpp test/Sema/warn-documentation.cpp

[Douglas Gregor]

On Aug 3, 2012, at 2:15 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> Author: gribozavr
> Date: Fri Aug  3 16:15:32 2012
> New Revision: 161261
> 
> URL: http://llvm.org/viewvc/llvm-project?rev=161261&view=rev
> Log:
> Comment diagnostics: warn if \returns is used in a non-function comment or if
> the function returns void.
> 
> Modified:
>    cfe/trunk/include/clang/AST/Comment.h
>    cfe/trunk/include/clang/AST/CommentSema.h
>    cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
>    cfe/trunk/lib/AST/Comment.cpp
>    cfe/trunk/lib/AST/CommentSema.cpp
>    cfe/trunk/test/Sema/warn-documentation.cpp
> 
> Modified: cfe/trunk/include/clang/AST/Comment.h
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/Comment.h?rev=161261&r1=161260&r2=161261&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/AST/Comment.h (original)
> +++ cfe/trunk/include/clang/AST/Comment.h Fri Aug  3 16:15:32 2012
> @@ -15,6 +15,7 @@
> #define LLVM_CLANG_AST_COMMENT_H
> 
> #include "clang/Basic/SourceLocation.h"
> +#include "clang/AST/Type.h"
> #include "llvm/ADT/ArrayRef.h"
> #include "llvm/ADT/StringRef.h"
> 
> @@ -919,6 +920,10 @@
>   /// that we consider a "function".
>   ArrayRef<const ParmVarDecl *> ParamVars;
> 
> +  /// Function result type if \c ThisDecl is something that we consider
> +  /// a "function".
> +  QualType ResultType;
> +
>   /// Template parameters that can be referenced by \\tparam if \c ThisDecl is
>   /// a template.
>   const TemplateParameterList *TemplateParameters;
> @@ -926,6 +931,9 @@
>   /// A simplified description of \c ThisDecl kind that should be good enough
>   /// for documentation rendering purposes.
>   enum DeclKind {
> +    /// Everything else not explicitly mentioned below.
> +    OtherKind,
> +
>     /// Something that we consider a "function":
>     /// \li function,
>     /// \li function template,
> 
> Modified: cfe/trunk/include/clang/AST/CommentSema.h
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentSema.h?rev=161261&r1=161260&r2=161261&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/AST/CommentSema.h (original)
> +++ cfe/trunk/include/clang/AST/CommentSema.h Fri Aug  3 16:15:32 2012
> @@ -181,6 +181,8 @@
> 
>   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
> 
> +  void checkReturnsCommand(const BlockCommandComment *Command);
> +
>   bool isFunctionDecl();
>   bool isTemplateDecl();
> 
> @@ -210,6 +212,7 @@
>   bool isBlockCommand(StringRef Name);
>   bool isParamCommand(StringRef Name);
>   bool isTParamCommand(StringRef Name);
> +  bool isReturnsCommand(StringRef Name);
>   unsigned getBlockCommandNumArgs(StringRef Name);
> 
>   bool isInlineCommand(StringRef Name) const;
> 
> Modified: cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td?rev=161261&r1=161260&r2=161261&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td (original)
> +++ cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td Fri Aug  3 16:15:32 2012
> @@ -98,5 +98,17 @@
> def note_doc_tparam_name_suggestion : Note<
>   "did you mean '%0'?">;
> 
> +// \returns command
> +
> +def warn_doc_returns_not_attached_to_a_function_decl : Warning<
> +  "'\\%0' command used in a comment that is not attached to "
> +  "a function declaration">,
> +  InGroup<Documentation>, DefaultIgnore;

"function or method", to cover ObjC methods?

> +def warn_doc_returns_attached_to_a_void_function : Warning<
> +  "'\\%0' command used in a comment that is attached to a "
> +  "%select{void function|constructor|destructor}1">,
> +  InGroup<Documentation>, DefaultIgnore;

Should the select also specialize for 'method', for ObjCMethodDecls?

	- Doug