doc parsing. We want to issue a strong warning when

an @function comment is not followed by a function decl.
// rdar://13094352

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@176468 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/include/clang/AST/CommentCommandTraits.h b/include/clang/AST/CommentCommandTraits.h
index ad4f29988c23885e13200d1c2940879c0a04e739..360a54b3781fc97c469ae97dd188cce964748cbb 100644 (file)
--- a/include/clang/AST/CommentCommandTraits.h
+++ b/include/clang/AST/CommentCommandTraits.h
@@ -100,7 +100,10 @@ struct CommandInfo {
   ///   \fn void f(int a);
   /// \endcode
   unsigned IsDeclarationCommand : 1;
-
+  
+  /// \brief True if verbatim-like line command is a function declaraton.
+  unsigned IsFunctionDeclarationCommand : 1;
+  
   /// \brief True if this command is unknown.  This \c CommandInfo object was
   /// created during parsing.
   unsigned IsUnknownCommand : 1;

diff --git a/include/clang/AST/CommentCommands.td b/include/clang/AST/CommentCommands.td
index f04509c5ca8ac91b494cf149d2400eb12516f3fc..50abc5948ce360ab5f50baeb1d008354e3482c47 100644 (file)
--- a/include/clang/AST/CommentCommands.td
+++ b/include/clang/AST/CommentCommands.td
@@ -24,6 +24,7 @@ class Command<string name> {
   bit IsVerbatimBlockEndCommand = 0;
   bit IsVerbatimLineCommand = 0;
   bit IsDeclarationCommand = 0;
+  bit IsFunctionDeclarationCommand = 0;
 }
 
 class InlineCommand<string name> : Command<name> {
@@ -59,6 +60,12 @@ class DeclarationVerbatimLineCommand<string name> :
   let IsDeclarationCommand = 1;
 }
 
+class FunctionDeclarationVerbatimLineCommand<string name> :
+      VerbatimLineCommand<name> {
+  let IsDeclarationCommand = 1;
+  let IsFunctionDeclarationCommand = 1;
+}
+
 //===----------------------------------------------------------------------===//
 // InlineCommand
 //===----------------------------------------------------------------------===//
@@ -179,7 +186,7 @@ def Interface : DeclarationVerbatimLineCommand<"interface">;
 def Protocol  : DeclarationVerbatimLineCommand<"protocol">;
 def Category  : DeclarationVerbatimLineCommand<"category">;
 def Template  : DeclarationVerbatimLineCommand<"template">;
-def Function  : DeclarationVerbatimLineCommand<"function">;
+def Function  : FunctionDeclarationVerbatimLineCommand<"function">;
 def Method    : DeclarationVerbatimLineCommand<"method">;
 def Callback  : DeclarationVerbatimLineCommand<"callback">;
 def Const     : DeclarationVerbatimLineCommand<"const">;

diff --git a/include/clang/AST/CommentSema.h b/include/clang/AST/CommentSema.h
index 6613feb3d7decd55a144d0bbaa4287b348df478f..6df48dcce1ab13fbac128c7286c5cc55f34df8ca 100644 (file)
--- a/include/clang/AST/CommentSema.h
+++ b/include/clang/AST/CommentSema.h
@@ -198,6 +198,8 @@ public:
   void checkBlockCommandDuplicate(const BlockCommandComment *Command);
 
   void checkDeprecatedCommand(const BlockCommandComment *Comment);
+  
+  void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
 
   /// Resolve parameter names to parameter indexes in function declaration.
   /// Emit diagnostics about unknown parametrs.

diff --git a/include/clang/Basic/DiagnosticCommentKinds.td b/include/clang/Basic/DiagnosticCommentKinds.td
index 829f98dfd75f4ca6517dc5246fb0180dae5e3aed..5f286251513af15c1ba4341b74f6afccc3bb6528 100644 (file)
--- a/include/clang/Basic/DiagnosticCommentKinds.td
+++ b/include/clang/Basic/DiagnosticCommentKinds.td
@@ -73,6 +73,11 @@ def warn_doc_param_not_attached_to_a_function_decl : Warning<
   "a function declaration">,
   InGroup<Documentation>, DefaultIgnore;
 
+def warn_doc_function_not_attached_to_a_function_decl : Warning<
+  "'@function' command used in a comment that is attached to "
+  "a non-function declaration immediately following it">,
+  InGroup<Documentation>, DefaultIgnore;
+  
 def warn_doc_param_duplicate : Warning<
   "parameter '%0' is already documented">,
   InGroup<Documentation>, DefaultIgnore;

diff --git a/lib/AST/CommentParser.cpp b/lib/AST/CommentParser.cpp
index 09912c6188645742acadd825718dfc4d89c40b4b..c361679e90567232871c5b76511e4230039bd60d 100644 (file)
--- a/lib/AST/CommentParser.cpp
+++ b/lib/AST/CommentParser.cpp
@@ -706,6 +706,8 @@ VerbatimLineComment *Parser::parseVerbatimLine() {
                                                 TextBegin,
                                                 Text);
   consumeToken();
+  S.checkFunctionDeclVerbatimLine(VL);
+  
   return VL;
 }
 

diff --git a/lib/AST/CommentSema.cpp b/lib/AST/CommentSema.cpp
index d959d19b916defafa3edd0a3b853b383a017649b..0cf7b5fd50d2e7969ad33a0d2e14f555171efa13 100644 (file)
--- a/lib/AST/CommentSema.cpp
+++ b/lib/AST/CommentSema.cpp
@@ -88,6 +88,15 @@ ParamCommandComment *Sema::actOnParamCommandStart(
   return Command;
 }
 
+void Sema::checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment) {
+  const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID());
+  if (Info->IsFunctionDeclarationCommand &&
+      !isFunctionDecl())
+    Diag(Comment->getLocation(),
+         diag::warn_doc_function_not_attached_to_a_function_decl)
+    << Comment->getSourceRange();
+}
+
 void Sema::actOnParamCommandDirectionArg(ParamCommandComment *Command,
                                          SourceLocation ArgLocBegin,
                                          SourceLocation ArgLocEnd,

diff --git a/test/Sema/warn-documentation.cpp b/test/Sema/warn-documentation.cpp
index 431bec1147940151713246dda010b4b98e7e4653..8b38ddd81a96e813244657514c815fef17bccfab 100644 (file)
--- a/test/Sema/warn-documentation.cpp
+++ b/test/Sema/warn-documentation.cpp
@@ -911,3 +911,12 @@ int test_nocrash12();
 ///@param x@param y
 int test_nocrash13(int x, int y);
 
+// expected-warning@+3 {{'@function' command used in a comment that is attached to a non-function declaration immediately following it}}
+// expected-warning@+3 {{'@param' command used in a comment that is not attached to a function declaration}}
+// expected-warning@+3 {{'@result' command used in a comment that is not attached to a function or method declaration}}
+/*!    @function Base64EncodeEx
+       @param  inFlags  This is error flag
+       @result Error
+*/
+typedef unsigned int Base64Flags;
+unsigned Base64EncodeEx(Base64Flags    inFlags);

diff --git a/utils/TableGen/ClangCommentCommandInfoEmitter.cpp b/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
index 4dafc2eec90373c5d80baf539d67ae8919c0687f..b0bf75217dd43f6776334f320e5ff567aeac6736 100644 (file)
--- a/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
+++ b/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
@@ -47,6 +47,7 @@ void EmitClangCommentCommandInfo(RecordKeeper &Records, raw_ostream &OS) {
        << Tag.getValueAsBit("IsVerbatimBlockEndCommand") << ", "
        << Tag.getValueAsBit("IsVerbatimLineCommand") << ", "
        << Tag.getValueAsBit("IsDeclarationCommand") << ", "
+       << Tag.getValueAsBit("IsFunctionDeclarationCommand") << ", "
        << /* IsUnknownCommand = */ "0"
        << " }";
     if (i + 1 != e)