WDocumentation: Implement the \anchor.

[Mordante]

Summary

I'm not sure it should be added to the InlineComment group. It's not entirely a markup. Do you think it should be a in a separate group?

(I also have not yet posted code for \emoji which is also in the InlineComment group.)

[gribozavr2]

Thank you for the contribution and sorry for the review delay!

clang/bindings/xml/comment-xml-schema.rng

583

Since the name of the anchor is not a part of the document text, it should be an attribute on the anchor tag (not a part of the text).

clang/lib/Index/CommentToXML.cpp

302

"name" is obsolete since HTML5. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a

I guess we should emit an empty "<span id=...>" instead.

303

I don't think escaping is needed. IDs have a strict syntax: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id

304

https://stackoverflow.com/questions/3558119/are-non-void-self-closing-tags-valid-in-html5

clang/test/Index/Inputs/CommentXML/valid-function-02.xml

12 ↗

(On Diff #225789)

I'd suggest to add a separate test file.

[Mordante]

Thanks for the review. I'll address your comments and upload a new version.

[Mordante]

Addresses review comments.

[gribozavr2]

A few more comments, but generally looks good!

clang/include/clang-c/Documentation.h

187

"since it is a only" => "since it only"

clang/lib/Index/CommentToXML.cpp

650

Sholudn't this code be producing "<anchor id=...>"?

clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml

2

Please add a line to clang/test/Index/comment-xml-schema.c that executes this test.

[Mordante]

clang/lib/Index/CommentToXML.cpp

650

Good catch, will update it in the next patch.

clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml

2

I already added a line.

clang/test/Index/comment-xml-schema.c

38

Is this what you meant? Or did you mean something different?

[gribozavr2]

clang/test/Index/comment-xml-schema.c

38

Yes, this line. Sorry, I missed it during review. Thanks for pointing out!

[Mordante]

Addresses review comments.

[gribozavr2]

With that last comment, LGTM. Do you have commit access?

clang/lib/AST/TextNodeDumper.cpp

493

Please add a test for this one to clang/test/Index/comment-to-html-xml-conversion.cpp (search for RenderEmphasized in that file).

[Mordante]

Thanks for the review! I recently acquired commit access so I'll commit it after updating the unit test.

clang/lib/AST/TextNodeDumper.cpp

493

I already added a test to clang/test/Index/comment-to-html-xml-conversion.cpp. I forgot to add a test to clang/test/AST/ast-dump-comment.cpp, is this the file you meant?

[Mordante]

clang/lib/AST/TextNodeDumper.cpp

493

@gribozavr2 In case you missed the question above, could you have a look at the question?

[gribozavr2]

LGTM, feel free to push.

clang/lib/AST/TextNodeDumper.cpp

493

Sorry, I probably missed your edit to clang/test/Index/comment-to-html-xml-conversion.cpp when typing that comment. ast-dump-comment.cpp is not as extensive, so I'm not concerned about having to add the test there. If you want to -- feel free, but I think that is optional.

clang/bindings/xml/comment-xml-schema.rng

<choice>
         </data>
       </element>
       <element name="emphasized">
         <!-- Non-empty text content. -->
         <data type="string">
           <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'. -->
           <!-- The value 'false' or absence of the attribute does not imply
                that the HTML is actually well-formed. -->
           <attribute name="isMalformed">
             <data type="boolean" />
           </attribute>

clang/include/clang-c/Documentation.h

enum CXCommentInlineCommandRenderKind {
    * Command argument should be rendered in a monospaced font.
    */
   CXCommentInlineCommandRenderKind_Monospaced,
 
   /**
    * 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
 };
 
 /**
  * Describes parameter passing direction for \\param or \\arg command.
  */
 enum CXCommentParamPassDirection {
   /**
    * The parameter is an input parameter.

clang/include/clang/AST/Comment.h

protected:
   };
   enum { NumTextCommentBits = NumInlineContentCommentBits + 2 };
 
   class InlineCommandCommentBitfields {
     friend class InlineCommandComment;
 
     unsigned : NumInlineContentCommentBits;
 
-    unsigned RenderKind : 2;
+    unsigned RenderKind : 3;
+
     unsigned CommandID : CommandInfo::NumCommandIDBits;
   };
-  enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 2 +
+  enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 3 +
                                        CommandInfo::NumCommandIDBits };
 
   class HTMLTagCommentBitfields {
     friend class HTMLTagComment;
 
     unsigned : NumInlineContentCommentBits;
 
     /// True if we found that this tag is malformed in some way.
public:
   };
 
   /// The most appropriate rendering mode for this command, chosen on command
   /// semantics in Doxygen.
   enum RenderKind {
     RenderNormal,
     RenderBold,
     RenderMonospaced,
-    RenderEmphasized
+    RenderEmphasized,
+    RenderAnchor
   };
 
 protected:
   /// Command arguments.
   ArrayRef<Argument> Args;
 
 public:
   InlineCommandComment(SourceLocation LocBegin,

clang/include/clang/AST/CommentCommands.td

class RecordLikeDeclarationVerbatimLineCommand<string name> :
       DeclarationVerbatimLineCommand<name> {
   let IsRecordLikeDeclarationCommand = 1;
 }
 
 //===----------------------------------------------------------------------===//
 // 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
 //===----------------------------------------------------------------------===//
 
 def Brief : BlockCommand<"brief"> { let IsBriefCommand = 1; }
 def Short : BlockCommand<"short"> { let IsBriefCommand = 1; }
 

clang/lib/AST/CommentSema.cpp

 InlineCommandComment::RenderKind
 Sema::getInlineCommandRenderKind(StringRef Name) const {
   assert(Traits.getCommandInfo(Name)->IsInlineCommand);
 
   return llvm::StringSwitch<InlineCommandComment::RenderKind>(Name)
       .Case("b", InlineCommandComment::RenderBold)
       .Cases("c", "p", InlineCommandComment::RenderMonospaced)
       .Cases("a", "e", "em", InlineCommandComment::RenderEmphasized)
+      .Case("anchor", InlineCommandComment::RenderAnchor)
       .Default(InlineCommandComment::RenderNormal);
 }
 
 } // end namespace comments
 } // end namespace clang

clang/lib/AST/JSONNodeDumper.cpp

case comments::InlineCommandComment::RenderBold:
     JOS.attribute("renderKind", "bold");
     break;
   case comments::InlineCommandComment::RenderEmphasized:
     JOS.attribute("renderKind", "emphasized");
     break;
   case comments::InlineCommandComment::RenderMonospaced:
     JOS.attribute("renderKind", "monospaced");
     break;
+  case comments::InlineCommandComment::RenderAnchor:
+    JOS.attribute("renderKind", "anchor");
+    break;
   }
 
   llvm::json::Array Args;
   for (unsigned I = 0, E = C->getNumArgs(); I < E; ++I)
     Args.push_back(C->getArgText(I));
 
   if (!Args.empty())
     JOS.attribute("args", std::move(Args));

clang/lib/AST/TextNodeDumper.cpp

case comments::InlineCommandComment::RenderBold:
     OS << " RenderBold";
     break;
   case comments::InlineCommandComment::RenderMonospaced:
     OS << " RenderMonospaced";
     break;
   case comments::InlineCommandComment::RenderEmphasized:
     OS << " RenderEmphasized";
     break;
+  case comments::InlineCommandComment::RenderAnchor:
+    OS << " RenderAnchor";
+    break;
   }
 
   for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i)
     OS << " Arg[" << i << "]=\"" << C->getArgText(i) << "\"";
 }
 
 void TextNodeDumper::visitHTMLStartTagComment(
     const comments::HTMLStartTagComment *C, const comments::FullComment *) {

clang/lib/Index/CommentToXML.cpp

case InlineCommandComment::RenderMonospaced:
     Result<< "</tt>";
     return;
   case InlineCommandComment::RenderEmphasized:
     assert(C->getNumArgs() == 1);
     Result << "<em>";
     appendToResultWithHTMLEscaping(Arg0);
     Result << "</em>";
     return;
+  case InlineCommandComment::RenderAnchor:
+    assert(C->getNumArgs() == 1);
+    Result << "<span id=\"" << Arg0 << "\"></span>";
+    return;
   }
 }
 
 void CommentASTToHTMLConverter::visitHTMLStartTagComment(
                                   const HTMLStartTagComment *C) {
   printHTMLStartTagComment(C, Result);
 }
 
 void CommentASTToHTMLConverter::visitHTMLEndTagComment(
case InlineCommandComment::RenderMonospaced:
     Result << "</monospaced>";
     return;
   case InlineCommandComment::RenderEmphasized:
     assert(C->getNumArgs() == 1);
     Result << "<emphasized>";
     appendToResultWithXMLEscaping(Arg0);
     Result << "</emphasized>";
     return;
+  case InlineCommandComment::RenderAnchor:
+    assert(C->getNumArgs() == 1);
+    Result << "<anchor id=\"" << Arg0 << "\"></anchor>";
+    return;
   }
 }
 
 void CommentASTToXMLConverter::visitHTMLStartTagComment(
     const HTMLStartTagComment *C) {
   Result << "<rawHTML";
   if (C->isMalformed())
     Result << " isMalformed=\"1\"";

clang/test/AST/ast-dump-comment.cpp

 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" xxx"
 
 /// \c Aaa
 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;
 // CHECK:      VarDecl{{.*}}Test_HTMLTagComment
 // CHECK-NEXT:   FullComment
 // CHECK-NEXT:     ParagraphComment
 // CHECK-NEXT:       TextComment{{.*}} Text=" "
 // CHECK-NEXT:       HTMLStartTagComment{{.*}} Name="a"

clang/test/Index/Inputs/CommentXML/valid-inline-command-01.xml

+<?xml version="1.0" encoding="utf-8"?>
+<Namespace>
+<Name>aaa</Name>
+<Abstract>
+  <Para>
+    <anchor id="aaa"></anchor>
+  </Para>
+</Abstract>
+</Namespace>

clang/test/Index/comment-to-html-xml-conversion.cpp

 // CHECK-NEXT:  CommentAST=[
 // CHECK-NEXT:    (CXComment_FullComment
 // CHECK-NEXT:       (CXComment_Paragraph
 // CHECK-NEXT:         (CXComment_Text Text=[ ] IsWhitespace)
 // CHECK-NEXT:         (CXComment_HTMLStartTag Name=[h1] Attrs: id=]]>)
 // 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 {
 // CHECK: comment-to-html-xml-conversion.cpp:[[@LINE-1]]:7: ClassDecl=comment_to_xml_conversion_01:{{.*}} FullCommentAsXML=[<Class file="{{[^"]+}}comment-to-html-xml-conversion.cpp" line="[[@LINE-1]]" column="7"><Name>comment_to_xml_conversion_01</Name><USR>c:@S@comment_to_xml_conversion_01</USR><Declaration>class comment_to_xml_conversion_01 {}</Declaration><Abstract><Para> Aaa.</Para></Abstract></Class>]
 
   /// \param aaa Blah blah.
   comment_to_xml_conversion_01(int aaa);
 

clang/test/Index/comment-xml-schema.c

 // RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-namespace-01.xml
 //
 // RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-typedef-01.xml
 // RUN: xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/valid-typedef-02.xml
 //
 // 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
 // RUN: not xmllint --noout --relaxng %S/../../bindings/xml/comment-xml-schema.rng %S/Inputs/CommentXML/invalid-function-03.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-04.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-05.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-06.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-07.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-08.xml 2>&1 | FileCheck %s -check-prefix=CHECK-INVALID

clang/test/Sema/warn-documentation.cpp

 // The inline comments expect a string after the command.
 // expected-warning@+1 {{'\a' command does not have a valid word argument}}
 /// \a
 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);
 
 /// @b A
 int test_inline_no_argument_b_good(int);
 
 // expected-warning@+1 {{'\c' command does not have a valid word argument}}

clang/tools/c-index-test/c-index-test.c

case CXCommentInlineCommandRenderKind_Bold:
       printf(" RenderBold");
       break;
     case CXCommentInlineCommandRenderKind_Monospaced:
       printf(" RenderMonospaced");
       break;
     case CXCommentInlineCommandRenderKind_Emphasized:
       printf(" RenderEmphasized");
       break;
+    case CXCommentInlineCommandRenderKind_Anchor:
+      printf(" RenderAnchor");
+      break;
     }
     for (i = 0, e = clang_InlineCommandComment_getNumArgs(Comment);
          i != e; ++i) {
       printf(" Arg[%u]=", i);
       PrintCXStringAndDispose(
           clang_InlineCommandComment_getArgText(Comment, i));
     }
     if (clang_InlineContentComment_hasTrailingNewline(Comment))

clang/tools/libclang/CXComment.cpp

clang_InlineCommandComment_getRenderKind(CXComment CXC) {
   case InlineCommandComment::RenderBold:
     return CXCommentInlineCommandRenderKind_Bold;
 
   case InlineCommandComment::RenderMonospaced:
     return CXCommentInlineCommandRenderKind_Monospaced;
 
   case InlineCommandComment::RenderEmphasized:
     return CXCommentInlineCommandRenderKind_Emphasized;
+
+  case InlineCommandComment::RenderAnchor:
+    return CXCommentInlineCommandRenderKind_Anchor;
   }
   llvm_unreachable("unknown InlineCommandComment::RenderKind");
 }
 
 unsigned clang_InlineCommandComment_getNumArgs(CXComment CXC) {
   const InlineCommandComment *ICC = getASTNodeAs<InlineCommandComment>(CXC);
   if (!ICC)
     return 0;