aaronpuchert created this revision.
aaronpuchert added reviewers: gribozavr2, Mordante.
Herald added a subscriber: arphaman.
aaronpuchert requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.
These should be all the commands from [1] except those that are marked
obsolete, and "link" / "endlink", as that conflicts with the existing
HeaderDoc pair "link / "/link". For some commands we don't have the
ideal category, but it should work good enough for most cases.
There seems to be no existing test for most commands (except the ones
interpreted by -Wdocumentation), and to some extent such a test wouldn't
look very interesting. But I added a test for the correct parsing of
formulas, as they're a bit special. And I had to adapt
comment-lots-of-unknown-commands.c because typo correction was kicking
in and recognizing some of the commands.
This should fix a couple of reported bugs: PR17437, PR19581, PR24062
(partially, no diagnostic for matching cond/endcond), PR32909, PR37813,
PR44243 (partially, em...@domain.com must be addressed separately).
[1] https://www.doxygen.nl/manual/commands.html
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D111190
Files:
clang/include/clang/AST/CommentCommands.td
clang/lib/AST/CommentLexer.cpp
clang/test/AST/ast-dump-comment.cpp
clang/test/Index/comment-lots-of-unknown-commands.c
clang/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
Index: clang/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
===================================================================
--- clang/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
+++ clang/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
@@ -83,6 +83,12 @@
default:
Mangled += Str[i];
break;
+ case '(':
+ Mangled += "lparen";
+ break;
+ case ')':
+ Mangled += "rparen";
+ break;
case '[':
Mangled += "lsquare";
break;
Index: clang/test/Index/comment-lots-of-unknown-commands.c
===================================================================
--- clang/test/Index/comment-lots-of-unknown-commands.c
+++ clang/test/Index/comment-lots-of-unknown-commands.c
@@ -39,7 +39,7 @@
@ien
@fr
@en
-@tet
+@teq
@le
@L
@os
@@ -77,7 +77,7 @@
@rU
@ar
@eD
-@iE
+@iEx
@se
@st1
@rr
@@ -106,7 +106,7 @@
@hd
@be
@It
-@id
+@idz
@cm
@ua
@fs
@@ -114,7 +114,7 @@
@axn
@rt
@to
-@is
+@isj
@fo
@i
@an
@@ -185,7 +185,7 @@
// CHECK: (CXComment_InlineCommand CommandName=[ien] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[fr] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[en] RenderNormal HasTrailingNewline)
-// CHECK: (CXComment_InlineCommand CommandName=[tet] RenderNormal HasTrailingNewline)
+// CHECK: (CXComment_InlineCommand CommandName=[teq] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[le] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[L] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[os] RenderNormal HasTrailingNewline)
@@ -223,7 +223,7 @@
// CHECK: (CXComment_InlineCommand CommandName=[rU] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[ar] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[eD] RenderNormal HasTrailingNewline)
-// CHECK: (CXComment_InlineCommand CommandName=[iE] RenderNormal HasTrailingNewline)
+// CHECK: (CXComment_InlineCommand CommandName=[iEx] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[se] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[st1] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[rr] RenderNormal HasTrailingNewline)
@@ -252,7 +252,7 @@
// CHECK: (CXComment_InlineCommand CommandName=[hd] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[be] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[It] RenderNormal HasTrailingNewline)
-// CHECK: (CXComment_InlineCommand CommandName=[id] RenderNormal HasTrailingNewline)
+// CHECK: (CXComment_InlineCommand CommandName=[idz] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[cm] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[ua] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[fs] RenderNormal HasTrailingNewline)
@@ -260,7 +260,7 @@
// CHECK: (CXComment_InlineCommand CommandName=[axn] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[rt] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[to] RenderNormal HasTrailingNewline)
-// CHECK: (CXComment_InlineCommand CommandName=[is] RenderNormal HasTrailingNewline)
+// CHECK: (CXComment_InlineCommand CommandName=[isj] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[fo] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[i] RenderNormal HasTrailingNewline)
// CHECK: (CXComment_InlineCommand CommandName=[an] RenderNormal HasTrailingNewline)
Index: clang/test/AST/ast-dump-comment.cpp
===================================================================
--- clang/test/AST/ast-dump-comment.cpp
+++ clang/test/AST/ast-dump-comment.cpp
@@ -76,10 +76,22 @@
/// \verbatim
/// Aaa
/// \endverbatim
+/// \f$ a \f$
+/// \f( b \f)
+/// \f[ c \f]
+/// \f{env}{ c \f}
int Test_VerbatimBlockComment;
// CHECK: VarDecl{{.*}}Test_VerbatimBlockComment
// CHECK: VerbatimBlockComment{{.*}} Name="verbatim" CloseName="endverbatim"
// CHECK-NEXT: VerbatimBlockLineComment{{.*}} Text=" Aaa"
+// CHECK: VerbatimBlockComment{{.*}} Name="f$" CloseName="f$"
+// CHECK-NEXT: VerbatimBlockLineComment{{.*}} Text=" a "
+// CHECK: VerbatimBlockComment{{.*}} Name="f(" CloseName="f)"
+// CHECK-NEXT: VerbatimBlockLineComment{{.*}} Text=" b "
+// CHECK: VerbatimBlockComment{{.*}} Name="f[" CloseName="f]"
+// CHECK-NEXT: VerbatimBlockLineComment{{.*}} Text=" c "
+// CHECK: VerbatimBlockComment{{.*}} Name="f{" CloseName="f}"
+// CHECK-NEXT: VerbatimBlockLineComment{{.*}} Text="env}{ c "
/// \param ... More arguments
template<typename T>
Index: clang/lib/AST/CommentLexer.cpp
===================================================================
--- clang/lib/AST/CommentLexer.cpp
+++ clang/lib/AST/CommentLexer.cpp
@@ -392,10 +392,11 @@
unsigned Length = TokenPtr - (BufferPtr + 1);
// Hardcoded support for lexing LaTeX formula commands
- // \f$ \f[ \f] \f{ \f} as a single command.
+ // \f$ \f( \f) \f[ \f] \f{ \f} as a single command.
if (Length == 1 && TokenPtr[-1] == 'f' && TokenPtr != CommentEnd) {
C = *TokenPtr;
- if (C == '$' || C == '[' || C == ']' || C == '{' || C == '}') {
+ if (C == '$' || C == '(' || C == ')' || C == '[' || C == ']' ||
+ C == '{' || C == '}') {
TokenPtr++;
Length++;
}
Index: clang/include/clang/AST/CommentCommands.td
===================================================================
--- clang/include/clang/AST/CommentCommands.td
+++ clang/include/clang/AST/CommentCommands.td
@@ -87,8 +87,21 @@
def A : InlineCommand<"a">;
def E : InlineCommand<"e">;
def Em : InlineCommand<"em">;
-def Ref : InlineCommand<"ref">;
-def Anchor : InlineCommand<"anchor">;
+def Emoji : InlineCommand<"emoji">;
+
+def Anchor : InlineCommand<"anchor">;
+def Ref : InlineCommand<"ref">;
+def RefItem : InlineCommand<"refitem">;
+def Cite : InlineCommand<"cite">;
+
+def CopyBrief : InlineCommand<"copybrief">;
+def CopyDetails : InlineCommand<"copydetails">;
+def CopyDoc : InlineCommand<"copydoc">;
+
+// Typically not used inline, but they take a single word.
+def Extends : InlineCommand<"extends">;
+def Implements : InlineCommand<"implements">;
+def MemberOf : InlineCommand<"memberof">;
//===----------------------------------------------------------------------===//
// BlockCommand
@@ -145,9 +158,11 @@
def Sa : BlockCommand<"sa">;
def See : BlockCommand<"see">;
def Since : BlockCommand<"since">;
+def Test : BlockCommand<"test">;
def Todo : BlockCommand<"todo">;
def Version : BlockCommand<"version">;
def Warning : BlockCommand<"warning">;
+def XRefItem : BlockCommand<"xrefitem">;
// HeaderDoc commands
def Abstract : BlockCommand<"abstract"> { let IsBriefCommand = 1; }
def ClassDesign : RecordLikeDetailCommand<"classdesign">;
@@ -170,6 +185,8 @@
defm Code : VerbatimBlockCommand<"code", "endcode">;
defm Verbatim : VerbatimBlockCommand<"verbatim", "endverbatim">;
+
+defm DocbookOnly : VerbatimBlockCommand<"docbookonly", "enddocbookonly">;
defm Htmlonly : VerbatimBlockCommand<"htmlonly", "endhtmlonly">;
defm Latexonly : VerbatimBlockCommand<"latexonly", "endlatexonly">;
defm Xmlonly : VerbatimBlockCommand<"xmlonly", "endxmlonly">;
@@ -178,10 +195,21 @@
defm Dot : VerbatimBlockCommand<"dot", "enddot">;
defm Msc : VerbatimBlockCommand<"msc", "endmsc">;
+defm Uml : VerbatimBlockCommand<"startuml", "enduml">;
+
+// Actually not verbatim blocks, we should also parse commands within them.
+// TODO: also support ifnot.
+defm If : VerbatimBlockCommand<"if", "endif">;
+defm Internal : VerbatimBlockCommand<"internal", "endinternal">;
+// TODO: conflicts with HeaderDoc link, /link.
+//defm Link : VerbatimBlockCommand<"link", "endlink">;
+defm ParBlock : VerbatimBlockCommand<"parblock", "endparblock">;
+defm SecRefList : VerbatimBlockCommand<"secreflist", "endsecreflist">;
// These three commands have special support in CommentLexer to recognize their
// names.
def FDollar : VerbatimBlockCommand<"f$">; // Inline LaTeX formula
+defm FParen : VerbatimBlockCommand<"f(", "f)">; // Inline LaTeX text
defm FBracket : VerbatimBlockCommand<"f[", "f]">; // Displayed LaTeX formula
defm FBrace : VerbatimBlockCommand<"f{", "f}">; // LaTeX environment
@@ -199,11 +227,17 @@
def Weakgroup : VerbatimLineCommand<"weakgroup">;
def Name : VerbatimLineCommand<"name">;
+// These actually take a single word, but it's optional.
+def Dir : VerbatimLineCommand<"dir">;
+def File : VerbatimLineCommand<"file">;
+
def Section : VerbatimLineCommand<"section">;
def Subsection : VerbatimLineCommand<"subsection">;
def Subsubsection : VerbatimLineCommand<"subsubsection">;
def Paragraph : VerbatimLineCommand<"paragraph">;
+def TableOfContents : VerbatimLineCommand<"tableofcontents">;
+def Page : VerbatimLineCommand<"page">;
def Mainpage : VerbatimLineCommand<"mainpage">;
def Subpage : VerbatimLineCommand<"subpage">;
@@ -212,13 +246,76 @@
def RelatesAlso : VerbatimLineCommand<"relatesalso">;
def RelatedAlso : VerbatimLineCommand<"relatedalso">;
+def AddIndex : VerbatimLineCommand<"addindex">;
+
+// These take a single argument mostly, but since they include a file they'll
+// typically be on their own line.
+def DocbookInclude : VerbatimLineCommand<"docbookinclude">;
+def DontInclude : VerbatimLineCommand<"dontinclude">;
+def Example : VerbatimLineCommand<"example">;
+def HtmlInclude : VerbatimLineCommand<"htmlinclude">;
+def Include : VerbatimLineCommand<"include">;
+def ManInclude : VerbatimLineCommand<"maninclude">;
+def LatexInclude : VerbatimLineCommand<"latexinclude">;
+def RtfInclude : VerbatimLineCommand<"rtfinclude">;
+def Snippet : VerbatimLineCommand<"snippet">;
+def VerbInclude : VerbatimLineCommand<"verbinclude">;
+def XmlInclude : VerbatimLineCommand<"xmlinclude">;
+
+def Image : VerbatimLineCommand<"image">;
+def DotFile : VerbatimLineCommand<"dotfile">;
+def MscFile : VerbatimLineCommand<"mscfile">;
+def DiaFile : VerbatimLineCommand<"diafile">;
+
+def Line : VerbatimLineCommand<"line">;
+def Skip : VerbatimLineCommand<"skip">;
+def SkipLine : VerbatimLineCommand<"skipline">;
+def Until : VerbatimLineCommand<"until">;
+
+def NoOp : VerbatimLineCommand<"noop">;
+
+// These have actually no arguments, but we can treat them as line commands.
+def CallGraph : VerbatimLineCommand<"callgraph">;
+def HideCallGraph : VerbatimLineCommand<"hidecallgraph">;
+def CallerGraph : VerbatimLineCommand<"callergraph">;
+def HideCallerGraph : VerbatimLineCommand<"hidecallergraph">;
+def ShowInitializer : VerbatimLineCommand<"showinitializer">;
+def HideInitializer : VerbatimLineCommand<"hideinitializer">;
+def ShowRefBy : VerbatimLineCommand<"showrefby">;
+def HideRefBy : VerbatimLineCommand<"hiderefby">;
+def ShowRefs : VerbatimLineCommand<"showrefs">;
+def HideRefs : VerbatimLineCommand<"hiderefs">;
+
+// These also have no argument.
+def Private : VerbatimLineCommand<"private">;
+def Protected : VerbatimLineCommand<"protected">;
+def Public : VerbatimLineCommand<"public">;
+def Pure : VerbatimLineCommand<"pure">;
+def Static : VerbatimLineCommand<"static">;
+
+// These also have no argument.
+def NoSubgrouping : VerbatimLineCommand<"nosubgrouping">;
+def PrivateSection : VerbatimLineCommand<"privatesection">;
+def ProtectedSection : VerbatimLineCommand<"protectedsection">;
+def PublicSection : VerbatimLineCommand<"publicsection">;
+
+// Not treated as VerbatimBlockCommand because it spans multiple comments.
+def Cond : VerbatimLineCommand<"cond">;
+def EndCond : VerbatimLineCommand<"endcond">;
+
+// We might also build proper support for if/ifnot/else/elseif/endif.
+def Else : VerbatimLineCommand<"else">;
+def ElseIf : VerbatimLineCommand<"elseif">;
+
//===----------------------------------------------------------------------===//
// DeclarationVerbatimLineCommand
//===----------------------------------------------------------------------===//
// Doxygen commands.
+def Concept : DeclarationVerbatimLineCommand<"concept">;
def Def : DeclarationVerbatimLineCommand<"def">;
def Fn : DeclarationVerbatimLineCommand<"fn">;
+def IDLExcept : DeclarationVerbatimLineCommand<"idlexcept">;
def Namespace : DeclarationVerbatimLineCommand<"namespace">;
def Overload : DeclarationVerbatimLineCommand<"overload">;
def Property : DeclarationVerbatimLineCommand<"property">;
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
