From 6fd7d3067dd06584ef3940e88e31fea1a0e83588 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Wed, 10 Apr 2013 15:35:17 +0000 Subject: [PATCH] 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 | 13 +++++++++++++ include/clang/AST/RawCommentList.h | 22 +++++++++++++++++----- include/clang/Basic/CommentOptions.h | 5 +++++ include/clang/Driver/Options.td | 1 + lib/AST/ASTContext.cpp | 4 +++- lib/AST/RawCommentList.cpp | 7 ++++--- lib/Driver/Tools.cpp | 2 ++ lib/Frontend/CompilerInvocation.cpp | 1 + lib/Sema/Sema.cpp | 3 ++- lib/Serialization/ASTReader.cpp | 7 ++++--- lib/Serialization/ASTWriter.cpp | 1 + 11 files changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 6cc836130f..97784f1b1b 100644 --- a/docs/UsersManual.rst +++ b/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 diff --git a/include/clang/AST/RawCommentList.h b/include/clang/AST/RawCommentList.h index 3a8b2183a5..7e8bf044c1 100644 --- a/include/clang/AST/RawCommentList.h +++ b/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 - diff --git a/include/clang/Basic/CommentOptions.h b/include/clang/Basic/CommentOptions.h index 79b9a6b883..7991875838 100644 --- a/include/clang/Basic/CommentOptions.h +++ b/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 diff --git a/include/clang/Driver/Options.td b/include/clang/Driver/Options.td index 112feb77b1..b9cf026fee 100644 --- a/include/clang/Driver/Options.td +++ b/include/clang/Driver/Options.td @@ -330,6 +330,7 @@ def fcolor_diagnostics : Flag<["-"], "fcolor-diagnostics">, Group, Flag def fcomment_block_commands : CommaJoined<["-"], "fcomment-block-commands=">, Group, Flags<[CC1Option]>, HelpText<"Treat each comma separated argument in as a documentation comment block command">, MetaVarName<"">; +def fparse_all_comments : Flag<["-"], "fparse-all-comments">, Group, Flags<[CC1Option]>; def fcommon : Flag<["-"], "fcommon">, Group; def fcompile_resource_EQ : Joined<["-"], "fcompile-resource=">, Group; def fconstant_cfstrings : Flag<["-"], "fconstant-cfstrings">, Group; diff --git a/lib/AST/ASTContext.cpp b/lib/AST/ASTContext.cpp index 7245c03160..170cc0298b 100644 --- a/lib/AST/ASTContext.cpp +++ b/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 Compare(SourceMgr); ArrayRef::iterator MaybeBeforeDecl = RawComments.end() - 1; bool Found = Compare(*MaybeBeforeDecl, &CommentAtDeclLoc); diff --git a/lib/AST/RawCommentList.cpp b/lib/AST/RawCommentList.cpp index f2386a56fc..7816459380 100644 --- a/lib/AST/RawCommentList.cpp +++ b/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; } - diff --git a/lib/Driver/Tools.cpp b/lib/Driver/Tools.cpp index 02ebc0448f..253c2dc7a1 100644 --- a/lib/Driver/Tools.cpp +++ b/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. diff --git a/lib/Frontend/CompilerInvocation.cpp b/lib/Frontend/CompilerInvocation.cpp index 324b6e3830..ed207e66fa 100644 --- a/lib/Frontend/CompilerInvocation.cpp +++ b/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, diff --git a/lib/Sema/Sema.cpp b/lib/Sema/Sema.cpp index e271f78ed0..6425f34ff5 100644 --- a/lib/Sema/Sema.cpp +++ b/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)); diff --git a/lib/Serialization/ASTReader.cpp b/lib/Serialization/ASTReader.cpp index d9844152b7..c8b3e93a87 100644 --- a/lib/Serialization/ASTReader.cpp +++ b/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; } } diff --git a/lib/Serialization/ASTWriter.cpp b/lib/Serialization/ASTWriter.cpp index cf93d1cf01..03e33ad369 100644 --- a/lib/Serialization/ASTWriter.cpp +++ b/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); -- 2.40.0