[Wdocumentation] Implement \anchor

Differential revision: https://reviews.llvm.org/D69223

15 files changed, 80 insertions, 10 deletions

diff --git a/clang/bindings/xml/comment-xml-schema.rng b/clang/bindings/xml/comment-xml-schema.rng
index 43f3e54c..65ea597 100644
--- a/clang/bindings/xml/comment-xml-schema.rng
+++ b/clang/bindings/xml/comment-xml-schema.rng
@@ -579,6 +579,14 @@
           <param name="pattern">.*\S.*</param>
         </data>
       </element>
+      <element name="anchor">
+        <attribute name="id">
+          <data type="string">
+            <!-- Non-empty text content without whitespace. -->
+            <param name="pattern">\S+</param>
+          </data>
+        </attribute>
+      </element>
       <element name="rawHTML">
         <optional>
           <!-- If not specified, the default value is 'false'. -->
diff --git a/clang/include/clang-c/Documentation.h b/clang/include/clang-c/Documentation.h
index ad3dd3b..5bece2c 100644
--- a/clang/include/clang-c/Documentation.h
+++ b/clang/include/clang-c/Documentation.h
@@ -181,7 +181,12 @@ enum CXCommentInlineCommandRenderKind {
    * Command argument should be rendered emphasized (typically italic
    * font).
    */
-  CXCommentInlineCommandRenderKind_Emphasized
+  CXCommentInlineCommandRenderKind_Emphasized,
+
+  /**
+   * Command argument should not be rendered (since it only defines an anchor).
+   */
+  CXCommentInlineCommandRenderKind_Anchor
 };
 
 /**
diff --git a/clang/include/clang/AST/Comment.h b/clang/include/clang/AST/Comment.h
index 2c284a2..cd9c1ce 100644
--- a/clang/include/clang/AST/Comment.h
+++ b/clang/include/clang/AST/Comment.h
@@ -94,10 +94,11 @@ protected:
 
     unsigned : NumInlineContentCommentBits;
 
-    unsigned RenderKind : 2;
+    unsigned RenderKind : 3;
+
     unsigned CommandID : CommandInfo::NumCommandIDBits;
   };
-  enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 2 +
+  enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 3 +
                                        CommandInfo::NumCommandIDBits };
 
   class HTMLTagCommentBitfields {
@@ -310,7 +311,8 @@ public:
     RenderNormal,
     RenderBold,
     RenderMonospaced,
-    RenderEmphasized
+    RenderEmphasized,
+    RenderAnchor
   };
 
 protected:
diff --git a/clang/include/clang/AST/CommentCommands.td b/clang/include/clang/AST/CommentCommands.td
index 3b0d160..d387df7 100644
--- a/clang/include/clang/AST/CommentCommands.td
+++ b/clang/include/clang/AST/CommentCommands.td
@@ -81,12 +81,13 @@ class RecordLikeDeclarationVerbatimLineCommand<string name> :
 // InlineCommand
 //===----------------------------------------------------------------------===//
 
-def B  : InlineCommand<"b">;
-def C  : InlineCommand<"c">;
-def P  : InlineCommand<"p">;
-def A  : InlineCommand<"a">;
-def E  : InlineCommand<"e">;
-def Em : InlineCommand<"em">;
+def B      : InlineCommand<"b">;
+def C      : InlineCommand<"c">;
+def P      : InlineCommand<"p">;
+def A      : InlineCommand<"a">;
+def E      : InlineCommand<"e">;
+def Em     : InlineCommand<"em">;
+def Anchor : InlineCommand<"anchor">;
 
 //===----------------------------------------------------------------------===//
 // BlockCommand
diff --git a/clang/lib/AST/CommentSema.cpp b/clang/lib/AST/CommentSema.cpp
index dda31e9..53c1832 100644
--- a/clang/lib/AST/CommentSema.cpp
+++ b/clang/lib/AST/CommentSema.cpp
@@ -1143,6 +1143,7 @@ Sema::getInlineCommandRenderKind(StringRef Name) const {
       .Case("b", InlineCommandComment::RenderBold)
       .Cases("c", "p", InlineCommandComment::RenderMonospaced)
       .Cases("a", "e", "em", InlineCommandComment::RenderEmphasized)
+      .Case("anchor", InlineCommandComment::RenderAnchor)
       .Default(InlineCommandComment::RenderNormal);
 }
 
diff --git a/clang/lib/AST/JSONNodeDumper.cpp b/clang/lib/AST/JSONNodeDumper.cpp
index 40c6c83..c30b071 100644
--- a/clang/lib/AST/JSONNodeDumper.cpp
+++ b/clang/lib/AST/JSONNodeDumper.cpp
@@ -1518,6 +1518,9 @@ void JSONNodeDumper::visitInlineCommandComment(
   case comments::InlineCommandComment::RenderMonospaced:
     JOS.attribute("renderKind", "monospaced");
     break;
+  case comments::InlineCommandComment::RenderAnchor:
+    JOS.attribute("renderKind", "anchor");
+    break;
   }
 
   llvm::json::Array Args;
diff --git a/clang/lib/AST/TextNodeDumper.cpp b/clang/lib/AST/TextNodeDumper.cpp
index 561c76a..fa7f413 100644
--- a/clang/lib/AST/TextNodeDumper.cpp
+++ b/clang/lib/AST/TextNodeDumper.cpp
@@ -489,6 +489,9 @@ void TextNodeDumper::visitInlineCommandComment(
   case comments::InlineCommandComment::RenderEmphasized:
     OS << " RenderEmphasized";
     break;
+  case comments::InlineCommandComment::RenderAnchor:
+    OS << " RenderAnchor";
+    break;
   }
 
   for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i)
diff --git a/clang/lib/Index/CommentToXML.cpp b/clang/lib/Index/CommentToXML.cpp
index 55923d6..ce6f9e2 100644
--- a/clang/lib/Index/CommentToXML.cpp
+++ b/clang/lib/Index/CommentToXML.cpp
@@ -297,6 +297,10 @@ void CommentASTToHTMLConverter::visitInlineCommandComment(
     appendToResultWithHTMLEscaping(Arg0);
     Result << "</em>";
     return;
+  case InlineCommandComment::RenderAnchor:
+    assert(C->getNumArgs() == 1);
+    Result << "<span id=\"" << Arg0 << "\"></span>";
+    return;
   }
 }
 
@@ -641,6 +645,10 @@ void CommentASTToXMLConverter::visitInlineCommandComment(
     appendToResultWithXMLEscaping(Arg0);
     Result << "</emphasized>";
     return;
+  case InlineCommandComment::RenderAnchor:
+    assert(C->getNumArgs() == 1);
+    Result << "<anchor id=\"" << Arg0 << "\"></anchor>";
+    return;
   }
 }
 
diff --git a/clang/test/AST/ast-dump-comment.cpp b/clang/test/AST/ast-dump-comment.cpp
index 5bd6934..da73483 100644
--- a/clang/test/AST/ast-dump-comment.cpp
+++ b/clang/test/AST/ast-dump-comment.cpp
@@ -47,6 +47,11 @@ int Test_InlineCommandComment;
 // CHECK:      VarDecl{{.*}}Test_InlineCommandComment
 // CHECK:        InlineCommandComment{{.*}} Name="c" RenderMonospaced Arg[0]="Aaa"
 
+/// \anchor Aaa
+int Test_InlineCommandCommentAnchor;
+// CHECK:      VarDecl{{.*}}Test_InlineCommandComment
+// CHECK:        InlineCommandComment{{.*}} Name="anchor" RenderAnchor Arg[0]="Aaa"
+
 /// <a>Aaa</a>
 /// <br/>
 int Test_HTMLTagComment;
diff --git a/clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml b/clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml
new file mode 100644
index 0000000..6f1a81c
--- /dev/null
+++ b/clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Namespace>
+<Name>aaa</Name>
+<Abstract>
+  <Para>
+    <anchor id="aaa"></anchor>
+  </Para>
+</Abstract>
+</Namespace>
diff --git a/clang/test/Index/comment-to-html-xml-conversion.cpp b/clang/test/Index/comment-to-html-xml-conversion.cpp
index 9e25ff1..bba5cf8 100644
--- a/clang/test/Index/comment-to-html-xml-conversion.cpp
+++ b/clang/test/Index/comment-to-html-xml-conversion.cpp
@@ -734,6 +734,16 @@ void comment_to_html_conversion_36();
 // CHECK-NEXT:         (CXComment_Text Text=[Aaa])
 // CHECK-NEXT:         (CXComment_HTMLEndTag Name=[h1])))]
 
+/// \anchor A
+void comment_to_html_conversion_37();
+
+// CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-2]]:6: FunctionDecl=comment_to_html_conversion_37:{{.*}} FullCommentAsHTML=[<p class="para-brief"> <span id="A"></span></p>] FullCommentAsXML=[<Function file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-2]]" column="6"><Name>comment_to_html_conversion_37</Name><USR>c:@F@comment_to_html_conversion_37#</USR><Declaration>void comment_to_html_conversion_37()</Declaration><Abstract><Para> <anchor id="A"></anchor></Para></Abstract></Function>]
+// CHECK-NEXT:  CommentAST=[
+// CHECK-NEXT:    (CXComment_FullComment
+// CHECK-NEXT:       (CXComment_Paragraph
+// CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
+// CHECK-NEXT:         (CXComment_InlineCommand CommandName=[anchor] RenderAnchor Arg[0]=A)))]
+
 
 /// Aaa.
 class comment_to_xml_conversion_01 {
diff --git a/clang/test/Index/comment-xml-schema.c b/clang/test/Index/comment-xml-schema.c
index 37cb47c..da529a5 100644
--- a/clang/test/Index/comment-xml-schema.c
+++ b/clang/test/Index/comment-xml-schema.c
@@ -33,6 +33,8 @@
 // RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-enum-01.xml
 //
 // RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-para-kind-01.xml
+//
+// RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-inline-command-01.xml
 
 // RUN: not xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/invalid-function-01.xml 2>&1 | FileCheck %s -check-prefix=CHECK-INVALID
 // RUN: not xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/invalid-function-02.xml 2>&1 | FileCheck %s -check-prefix=CHECK-INVALID
diff --git a/clang/test/Sema/warn-documentation.cpp b/clang/test/Sema/warn-documentation.cpp
index 3cd3728..3091c2f 100644
--- a/clang/test/Sema/warn-documentation.cpp
+++ b/clang/test/Sema/warn-documentation.cpp
@@ -1102,6 +1102,13 @@ int test_inline_no_argument_a_bad(int);
 /// \a A
 int test_inline_no_argument_a_good(int);
 
+// expected-warning@+1 {{'\anchor' command does not have a valid word argument}}
+/// \anchor
+int test_inline_no_argument_anchor_bad(int);
+
+/// \anchor A
+int test_inline_no_argument_anchor_good(int);
+
 // expected-warning@+1 {{'@b' command does not have a valid word argument}}
 /// @b
 int test_inline_no_argument_b_bad(int);
diff --git a/clang/tools/c-index-test/c-index-test.c b/clang/tools/c-index-test/c-index-test.c
index dc7e449..d4de743 100644
--- a/clang/tools/c-index-test/c-index-test.c
+++ b/clang/tools/c-index-test/c-index-test.c
@@ -497,6 +497,9 @@ static void DumpCXCommentInternal(struct CommentASTDumpingContext *Ctx,
     case CXCommentInlineCommandRenderKind_Emphasized:
       printf(" RenderEmphasized");
       break;
+    case CXCommentInlineCommandRenderKind_Anchor:
+      printf(" RenderAnchor");
+      break;
     }
     for (i = 0, e = clang_InlineCommandComment_getNumArgs(Comment);
          i != e; ++i) {
diff --git a/clang/tools/libclang/CXComment.cpp b/clang/tools/libclang/CXComment.cpp
index cb27b25..bafaeb0 100644
--- a/clang/tools/libclang/CXComment.cpp
+++ b/clang/tools/libclang/CXComment.cpp
@@ -159,6 +159,9 @@ clang_InlineCommandComment_getRenderKind(CXComment CXC) {
 
   case InlineCommandComment::RenderEmphasized:
     return CXCommentInlineCommandRenderKind_Emphasized;
+
+  case InlineCommandComment::RenderAnchor:
+    return CXCommentInlineCommandRenderKind_Anchor;
   }
   llvm_unreachable("unknown InlineCommandComment::RenderKind");
 }