Add an option to parse all comments as documentation comments

Patch by Amin Shali.


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

docs/UsersManual.rst

@@ -1005,6 +1005,19 @@ below. If multiple flags are present, the last one is used.
 
   Generate complete debug info.
 
+Comment Parsing Options
+--------------------------
+
+Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes.  By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with ``//`` and
+``/*``.
+
+.. option:: -fparse-all-comments
+
+  Parse all comments as documentation comments (including ordinary comments
+  starting with ``//`` and ``/*``).
+
 .. _c:
 
 C Language Features

include/clang/AST/RawCommentList.h

@@ -10,6 +10,7 @@
 #ifndef LLVM_CLANG_AST_RAW_COMMENT_LIST_H
 #define LLVM_CLANG_AST_RAW_COMMENT_LIST_H
 
+#include "clang/Basic/CommentOptions.h"
 #include "clang/Basic/SourceManager.h"
 #include "llvm/ADT/ArrayRef.h"
 
@@ -40,7 +41,7 @@ public:
   RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
 
   RawComment(const SourceManager &SourceMgr, SourceRange SR,
-             bool Merged = false);
+             bool Merged, bool ParseAllComments);
 
   CommentKind getKind() const LLVM_READONLY {
     return (CommentKind) Kind;
@@ -82,12 +83,18 @@ public:
 
   /// Returns true if this comment is not a documentation comment.
   bool isOrdinary() const LLVM_READONLY {
-    return (Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC);
+    return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC)) &&
+        !ParseAllComments;
   }
 
   /// Returns true if this comment any kind of a documentation comment.
   bool isDocumentation() const LLVM_READONLY {
-    return !isInvalid() && !isOrdinary();
+    return !isInvalid() && (!isOrdinary() || ParseAllComments);
+  }
+
+  /// Returns whether we are parsing all comments.
+  bool isParseAllComments() const LLVM_READONLY {
+    return ParseAllComments;
   }
 
   /// Returns raw comment text with comment markers.
@@ -135,6 +142,10 @@ private:
   bool IsTrailingComment : 1;
   bool IsAlmostTrailingComment : 1;
 
+  /// When true, ordinary comments starting with "//" and "/*" will be
+  /// considered as documentation comments.
+  bool ParseAllComments : 1;
+
   mutable bool BeginLineValid : 1; ///< True if BeginLine is valid
   mutable bool EndLineValid : 1;   ///< True if EndLine is valid
   mutable unsigned BeginLine;      ///< Cached line number
@@ -142,10 +153,12 @@ private:
 
   /// \brief Constructor for AST deserialization.
   RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
-             bool IsAlmostTrailingComment) :
+             bool IsAlmostTrailingComment,
+             bool ParseAllComments) :
     Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
     IsAttached(false), IsTrailingComment(IsTrailingComment),
     IsAlmostTrailingComment(IsAlmostTrailingComment),
+    ParseAllComments(ParseAllComments),
     BeginLineValid(false), EndLineValid(false)
   { }
 
@@ -207,4 +220,3 @@ private:
 } // end namespace clang
 
 #endif
-

include/clang/Basic/CommentOptions.h

@@ -27,6 +27,11 @@ struct CommentOptions {
   /// \brief Command names to treat as block commands in comments.
   /// Should not include the leading backslash.
   BlockCommandNamesTy BlockCommandNames;
+
+  /// \brief Treat ordinary comments as documentation comments.
+  bool ParseAllComments;
+
+  CommentOptions() : ParseAllComments(false) { }
 };
 
 }  // end namespace clang

include/clang/Driver/Options.td

@@ -330,6 +330,7 @@ def fcolor_diagnostics : Flag<["-"], "fcolor-diagnostics">, Group<f_Group>, Flag
 def fcomment_block_commands : CommaJoined<["-"], "fcomment-block-commands=">, Group<f_clang_Group>, Flags<[CC1Option]>,
   HelpText<"Treat each comma separated argument in <arg> as a documentation comment block command">,
   MetaVarName<"<arg>">;
+def fparse_all_comments : Flag<["-"], "fparse-all-comments">, Group<f_clang_Group>, Flags<[CC1Option]>;
 def fcommon : Flag<["-"], "fcommon">, Group<f_Group>;
 def fcompile_resource_EQ : Joined<["-"], "fcompile-resource=">, Group<f_Group>;
 def fconstant_cfstrings : Flag<["-"], "fconstant-cfstrings">, Group<f_Group>;

lib/AST/ASTContext.cpp

@@ -141,7 +141,9 @@ RawComment *ASTContext::getRawCommentForDeclNoCache(const Decl *D) const {
     // When searching for comments during parsing, the comment we are looking
     // for is usually among the last two comments we parsed -- check them
     // first.
-    RawComment CommentAtDeclLoc(SourceMgr, SourceRange(DeclLoc));
+    RawComment CommentAtDeclLoc(
+        SourceMgr, SourceRange(DeclLoc), false,
+        LangOpts.CommentOpts.ParseAllComments);
     BeforeThanCompare<RawComment> Compare(SourceMgr);
     ArrayRef<RawComment *>::iterator MaybeBeforeDecl = RawComments.end() - 1;
     bool Found = Compare(*MaybeBeforeDecl, &CommentAtDeclLoc);

lib/AST/RawCommentList.cpp

@@ -63,9 +63,10 @@ bool mergedCommentIsTrailingComment(StringRef Comment) {
 } // unnamed namespace
 
 RawComment::RawComment(const SourceManager &SourceMgr, SourceRange SR,
-                       bool Merged) :
+                       bool Merged, bool ParseAllComments) :
     Range(SR), RawTextValid(false), BriefTextValid(false),
     IsAttached(false), IsAlmostTrailingComment(false),
+    ParseAllComments(ParseAllComments),
     BeginLineValid(false), EndLineValid(false) {
   // Extract raw comment text, if possible.
   if (SR.getBegin() == SR.getEnd() || getRawText(SourceMgr).empty()) {
@@ -253,7 +254,8 @@ void RawCommentList::addComment(const RawComment &RC,
     if (C1EndLine + 1 == C2BeginLine || C1EndLine == C2BeginLine) {
       SourceRange MergedRange(C1.getSourceRange().getBegin(),
                               C2.getSourceRange().getEnd());
-      *Comments.back() = RawComment(SourceMgr, MergedRange, true);
+      *Comments.back() = RawComment(SourceMgr, MergedRange, true,
+                                    RC.isParseAllComments());
       Merged = true;
     }
   }
@@ -262,4 +264,3 @@ void RawCommentList::addComment(const RawComment &RC,
 
   OnlyWhitespaceSeen = true;
 }
-

lib/Driver/Tools.cpp

@@ -3294,6 +3294,8 @@ void Clang::ConstructJob(Compilation &C, const JobAction &JA,
 
   // Forward -fcomment-block-commands to -cc1.
   Args.AddAllArgs(CmdArgs, options::OPT_fcomment_block_commands);
+  // Forward -fparse-all-comments to -cc1.
+  Args.AddAllArgs(CmdArgs, options::OPT_fparse_all_comments);
 
   // Forward -Xclang arguments to -cc1, and -mllvm arguments to the LLVM option
   // parser.

lib/Frontend/CompilerInvocation.cpp

@@ -281,6 +281,7 @@ static bool ParseMigratorArgs(MigratorOptions &Opts, ArgList &Args) {
 
 static void ParseCommentArgs(CommentOptions &Opts, ArgList &Args) {
   Opts.BlockCommandNames = Args.getAllArgValues(OPT_fcomment_block_commands);
+  Opts.ParseAllComments = Args.hasArg(OPT_fparse_all_comments);
 }
 
 static bool ParseCodeGenArgs(CodeGenOptions &Opts, ArgList &Args, InputKind IK,

lib/Sema/Sema.cpp

@@ -1077,7 +1077,8 @@ void Sema::ActOnComment(SourceRange Comment) {
   if (!LangOpts.RetainCommentsFromSystemHeaders &&
       SourceMgr.isInSystemHeader(Comment.getBegin()))
     return;
-  RawComment RC(SourceMgr, Comment);
+  RawComment RC(SourceMgr, Comment, false,
+                LangOpts.CommentOpts.ParseAllComments);
   if (RC.isAlmostTrailingComment()) {
     SourceRange MagicMarkerRange(Comment.getBegin(),
                                  Comment.getBegin().getLocWithOffset(3));

lib/Serialization/ASTReader.cpp

@@ -3907,6 +3907,7 @@ bool ASTReader::ParseLanguageOptions(const RecordData &Record,
     LangOpts.CommentOpts.BlockCommandNames.push_back(
       ReadString(Record, Idx));
   }
+  LangOpts.CommentOpts.ParseAllComments = Record[Idx++];
 
   return Listener.ReadLanguageOptions(LangOpts, Complain);
 }
@@ -7165,9 +7166,9 @@ void ASTReader::ReadComments() {
             (RawComment::CommentKind) Record[Idx++];
         bool IsTrailingComment = Record[Idx++];
         bool IsAlmostTrailingComment = Record[Idx++];
-        Comments.push_back(new (Context) RawComment(SR, Kind,
-                                                    IsTrailingComment,
-                                                    IsAlmostTrailingComment));
+        Comments.push_back(new (Context) RawComment(
+            SR, Kind, IsTrailingComment, IsAlmostTrailingComment,
+            Context.getLangOpts().CommentOpts.ParseAllComments));
         break;
       }
       }

lib/Serialization/ASTWriter.cpp

@@ -1069,6 +1069,7 @@ void ASTWriter::WriteControlBlock(Preprocessor &PP, ASTContext &Context,
        I != IEnd; ++I) {
     AddString(*I, Record);
   }
+  Record.push_back(LangOpts.CommentOpts.ParseAllComments);
 
   Stream.EmitRecord(LANGUAGE_OPTIONS, Record);