Skip to content
Permalink
Browse files
[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
  • Loading branch information
bitjammer committed Jun 22, 2017
1 parent ce8c0eb commit a85e1d6f308600ff0f3c79ee54291828fc122998
Showing 3 changed files with 60 additions and 0 deletions.
@@ -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. -->
@@ -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)
@@ -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>]

0 comments on commit a85e1d6

Please sign in to comment.