[Markup] Print Tags in documentation comment XML

This information needs to be picked up through SourceKit. It might be useful as both metadata for sorting/filtering as well as presentation, so it makes sense to print it in the normal XML inside CommentParts. rdar://problem/32877771
swiftlang · Jun 22, 2017 · a85e1d6 · a85e1d6
1 parent ce8c0eb
commit a85e1d6
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 0 deletions.
diff --git a/bindings/xml/comment-xml-schema.rng b/bindings/xml/comment-xml-schema.rng
@@ -46,6 +46,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
         <optional>
           <ref name="Discussion" />
         </optional>
@@ -115,6 +118,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
         <optional>
           <ref name="Discussion" />
         </optional>
@@ -166,6 +172,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
 
         <optional>
           <ref name="Discussion" />
@@ -209,6 +218,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
 
         <optional>
           <ref name="Discussion" />
@@ -252,6 +264,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
 
         <optional>
           <ref name="Discussion" />
@@ -294,6 +309,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
 
         <optional>
           <ref name="Discussion" />
@@ -337,6 +355,9 @@
         <optional>
           <ref name="ResultDiscussion" />
         </optional>
+        <optional>
+          <ref name="Tags" />
+        </optional>
 
         <optional>
           <ref name="Discussion" />
@@ -640,6 +661,16 @@
     </element>
   </define>
 
+  <define name="Tags">
+    <element name="Tags">
+      <oneOrMore>
+        <element name="Tag">
+          <data type="string" />
+        </element>
+      </oneOrMore>
+    </element>
+  </define>
+
   <define name="Parameters">
     <element name="Parameters">
       <!-- Parameter elements should be sorted according to index. -->

diff --git a/lib/IDE/CommentConversion.cpp b/lib/IDE/CommentConversion.cpp
@@ -245,6 +245,19 @@ struct CommentToXMLConverter {
     OS << "</ThrowsDiscussion>";
   }
 
+  void printTagFields(ArrayRef<StringRef> Tags) {
+    OS << "<Tags>";
+    for (const auto Tag : Tags) {
+      if (Tag.empty()) {
+        continue;
+      }
+      OS << "<Tag>";
+      appendWithXMLEscaping(OS, Tag);
+      OS << "</Tag>";
+    }
+    OS << "</Tags>";
+  }
+
   void visitDocComment(const DocComment *DC);
   void visitCommentParts(const swift::markup::CommentParts &Parts);
 };
@@ -271,6 +284,10 @@ void CommentToXMLConverter::visitCommentParts(const swift::markup::CommentParts
   if (Parts.ThrowsField.hasValue())
     printThrowsDiscussion(Parts.ThrowsField.getValue());
 
+  if (!Parts.Tags.empty()) {
+    printTagFields(Parts.Tags);
+  }
+
   if (!Parts.BodyNodes.empty()) {
     OS << "<Discussion>";
     for (const auto *N : Parts.BodyNodes)

diff --git a/test/Inputs/comment_to_something_conversion.swift b/test/Inputs/comment_to_something_conversion.swift
@@ -477,3 +477,15 @@ public func localizationKeyShouldNotAppearInDocComments() {}
 /// - LocalizationKey: ABC
 public func localizationKeyShouldNotAppearInDocComments2() {}
 // CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>localizationKeyShouldNotAppearInDocComments2()</Name><USR>s:14comment_to_xml44localizationKeyShouldNotAppearInDocComments2yyF</USR><Declaration>public func localizationKeyShouldNotAppearInDocComments2()</Declaration><CommentParts></CommentParts></Function>]
+
+/// Brief.
+///
+/// - Tag:
+/// - Tag:  
+/// - Tag: Tag_A
+/// - Tag: Tag B
+/// - Tag: Dedupe tag
+/// - Tag: Dedupe tag
+/// - TAG: TAG_C
+public func tags() {}
+// CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>tags()</Name><USR>s:14comment_to_xml4tagsyyF</USR><Declaration>public func tags()</Declaration><CommentParts><Abstract><Para>Brief.</Para></Abstract><Tags><Tag>Tag_A</Tag><Tag>Tag B</Tag><Tag>Dedupe tag</Tag><Tag>TAG_C</Tag></Tags></CommentParts></Function>]