Skip to content

Commit 3566c7d

Browse files
bitjammerbitjammer
committed
Merge pull request #2133 from bitjammer/closure-param-doc
Add rudimentary nested closure param/return/throws support for Doxygen
2 parents efd04e9 + 0f71dfd commit 3566c7d

File tree

3 files changed

+184
-39
lines changed

3 files changed

+184
-39
lines changed

‎lib/IDE/CommentConversion.cpp

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -632,13 +632,78 @@ break;
632632
llvm_unreachable("Can't directly print Doxygen for a Swift Markup PrivateExtension");
633633
}
634634

635+
void printNestedParamField(const ParamField *PF) {
636+
auto Parts = PF->getParts().getValue();
637+
if (Parts.Brief.hasValue()) {
638+
printASTNode(Parts.Brief.getValue());
639+
printNewline();
640+
}
641+
642+
if (!Parts.ParamFields.empty()) {
643+
printNewline();
644+
print("\\a ");
645+
print(PF->getName());
646+
print(" parameters:");
647+
printNewline();
648+
649+
print("<ul>");
650+
printNewline();
651+
for (auto Param : Parts.ParamFields) {
652+
print("<li>");
653+
printNewline();
654+
print(Param->getName());
655+
print(": ");
656+
printNestedParamField(Param);
657+
print("</li>");
658+
printNewline();
659+
}
660+
print("</ul>");
661+
printNewline();
662+
printNewline();
663+
}
664+
665+
if (Parts.ReturnsField.hasValue()) {
666+
printNewline();
667+
print("\\a ");
668+
print(PF->getName());
669+
print(" returns: ");
670+
671+
for (auto Child : Parts.ReturnsField.getValue()->getChildren()) {
672+
printASTNode(Child);
673+
printNewline();
674+
}
675+
}
676+
677+
if (Parts.ThrowsField.hasValue()) {
678+
printNewline();
679+
print("\\a ");
680+
print(PF->getName());
681+
print(" error: ");
682+
683+
for (auto Child : Parts.ThrowsField.getValue()->getChildren()) {
684+
printASTNode(Child);
685+
printNewline();
686+
}
687+
}
688+
689+
for (auto BodyNode : Parts.BodyNodes) {
690+
printASTNode(BodyNode);
691+
printNewline();
692+
}
693+
printNewline();
694+
}
695+
635696
void printParamField(const ParamField *PF) {
636697
print("\\param ");
637698
print(PF->getName());
638699
print(" ");
639-
for (auto Child : PF->getChildren())
640-
printASTNode(Child);
641-
700+
if (PF->isClosureParameter()) {
701+
printNestedParamField(PF);
702+
} else {
703+
for (auto Child : PF->getChildren()) {
704+
printASTNode(Child);
705+
}
706+
}
642707
printNewline();
643708
}
644709

‎test/Inputs/comment_to_something_conversion.swift

Lines changed: 38 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,44 @@ public enum A012_AttachToEntities {
107107
// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>f3()</Name><USR>s:FC14swift_ide_test5Brief2f3FT_T_</USR><Declaration>public func f3()</Declaration><Abstract><Para>Aaa.</Para></Abstract><Discussion><Para>Bbb.</Para></Discussion></Function>]
108108
}
109109

110+
@objc public class ClosureContainer {
111+
/// Partially applies a binary operator.
112+
///
113+
/// - Parameter a: The left-hand side to partially apply.
114+
/// - Parameter combine: A binary operator.
115+
/// - Parameter lhs: The left-hand side of the operator
116+
/// - Parameter rhs: The right-hand side of the operator
117+
/// - Returns: A result.
118+
/// - Throws: Nothing.
119+
@objc public func closureParameterExplodedExploded(a: Int, combine: (lhs: Int, rhs: Int) -> Int) {}
120+
// CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>closureParameterExplodedExploded(a:combine:)</Name><USR>s:FC14swift_ide_test16ClosureContainer32closureParameterExplodedExplodedFT1aSi7combineFT3lhsSi3rhsSi_Si_T_</USR><Declaration>@objc public func closureParameterExplodedExploded(a: Int, combine: (lhs: Int, rhs: Int) -&gt; Int)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>]
121+
122+
/// Partially applies a binary operator.
123+
///
124+
/// - Parameters:
125+
/// - a: The left-hand side to partially apply.
126+
/// - combine: A binary operator.
127+
/// - Parameter lhs: The left-hand side of the operator
128+
/// - Parameter rhs: The right-hand side of the operator
129+
/// - Returns: A result.
130+
/// - Throws: Nothing.
131+
@objc public func closureParameterOutlineExploded(a: Int, combine: (lhs: Int, rhs: Int) -> Int) {}
132+
// CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>closureParameterOutlineExploded(a:combine:)</Name><USR>s:FC14swift_ide_test16ClosureContainer31closureParameterOutlineExplodedFT1aSi7combineFT3lhsSi3rhsSi_Si_T_</USR><Declaration>@objc public func closureParameterOutlineExploded(a: Int, combine: (lhs: Int, rhs: Int) -&gt; Int)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>]
133+
134+
/// Partially applies a binary operator.
135+
///
136+
/// - Parameters:
137+
/// - a: The left-hand side to partially apply.
138+
/// - combine: A binary operator.
139+
/// - Parameters:
140+
/// - lhs: The left-hand side of the operator
141+
/// - rhs: The right-hand side of the operator
142+
/// - Returns: A result.
143+
/// - Throws: Nothing.
144+
@objc public func closureParameterOutlineOutline(a: Int, combine: (lhs: Int, rhs: Int) -> Int) {}
145+
// CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>closureParameterOutlineOutline(a:combine:)</Name><USR>s:FC14swift_ide_test16ClosureContainer30closureParameterOutlineOutlineFT1aSi7combineFT3lhsSi3rhsSi_Si_T_</USR><Declaration>@objc public func closureParameterOutlineOutline(a: Int, combine: (lhs: Int, rhs: Int) -&gt; Int)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>]
146+
}
147+
110148
@objc public class CodeBlock {
111149
// CHECK: {{.*}}DocCommentAsXML=none
112150
/// This is how you use this code.
@@ -422,39 +460,3 @@ public func codeListingWithDefaultLanguage() {}
422460
/// ```
423461
public func codeListingWithOtherLanguage() {}
424462
// CHECK: DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>codeListingWithOtherLanguage()</Name><USR>s:F14swift_ide_test28codeListingWithOtherLanguageFT_T_</USR><Declaration>public func codeListingWithOtherLanguage()</Declaration><Abstract><Para>Brief.</Para></Abstract><Discussion><CodeListing language="c++"><zCodeLineNumbered><![CDATA[Something::Something::create();]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>]
425-
426-
/// Partially applies a binary operator.
427-
///
428-
/// - Parameter a: The left-hand side to partially apply.
429-
/// - Parameter combine: A binary operator.
430-
/// - Parameter lhs: The left-hand side of the operator
431-
/// - Parameter rhs: The right-hand side of the operator
432-
/// - Returns: A result.
433-
/// - Throws: Nothing.
434-
public func closureParameterExplodedExploded<T>(a: T, combine: (lhs: T, rhs: T) -> T) {}
435-
// CHECK: DocCommentAsXML=[<Function file="{{.*}} line="{{.*}}" column="{{.*}}"><Name>closureParameterExplodedExploded(a:combine:)</Name><USR>s:F14swift_ide_test32closureParameterExplodedExplodedurFT1ax7combineFT3lhsx3rhsx_x_T_</USR><Declaration>public func closureParameterExplodedExploded&lt;T&gt;(a: T, combine: (lhs: T, rhs: T) -&gt; T)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>] CommentXMLValid
436-
437-
/// Partially applies a binary operator.
438-
///
439-
/// - Parameters:
440-
/// - a: The left-hand side to partially apply.
441-
/// - combine: A binary operator.
442-
/// - Parameter lhs: The left-hand side of the operator
443-
/// - Parameter rhs: The right-hand side of the operator
444-
/// - Returns: A result.
445-
/// - Throws: Nothing.
446-
public func closureParameterOutlineExploded<T>(a: T, combine: (lhs: T, rhs: T) -> T) {}
447-
// CHECK: DocCommentAsXML=[<Function file="{{.*}} line="{{.*}}" column="{{.*}}"><Name>closureParameterOutlineExploded(a:combine:)</Name><USR>s:F14swift_ide_test31closureParameterOutlineExplodedurFT1ax7combineFT3lhsx3rhsx_x_T_</USR><Declaration>public func closureParameterOutlineExploded&lt;T&gt;(a: T, combine: (lhs: T, rhs: T) -&gt; T)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>] CommentXMLValid
448-
449-
/// Partially applies a binary operator.
450-
///
451-
/// - Parameters:
452-
/// - a: The left-hand side to partially apply.
453-
/// - combine: A binary operator.
454-
/// - Parameters:
455-
/// - lhs: The left-hand side of the operator
456-
/// - rhs: The right-hand side of the operator
457-
/// - Returns: A result.
458-
/// - Throws: Nothing.
459-
public func closureParameterOutlineOutline<T>(a: T, combine: (lhs: T, rhs: T) -> T) {}
460-
// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>closureParameterOutlineOutline(a:combine:)</Name><USR>s:F14swift_ide_test30closureParameterOutlineOutlineurFT1ax7combineFT3lhsx3rhsx_x_T_</USR><Declaration>public func closureParameterOutlineOutline&lt;T&gt;(a: T, combine: (lhs: T, rhs: T) -&gt; T)</Declaration><Abstract><Para>Partially applies a binary operator.</Para></Abstract><Parameters><Parameter><Name>a</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side to partially apply.</Para></Discussion></Parameter><Parameter><Name>combine</Name><Direction isExplicit="0">in</Direction><ClosureParameter><Abstract><Para>A binary operator.</Para></Abstract><Parameters><Parameter><Name>lhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The left-hand side of the operator</Para></Discussion></Parameter><Parameter><Name>rhs</Name><Direction isExplicit="0">in</Direction><Discussion><Para>The right-hand side of the operator</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A result.</Para></ResultDiscussion><ThrowsDiscussion><Para>Nothing.</Para></ThrowsDiscussion></ClosureParameter></Parameter></Parameters></Function>]

‎test/PrintAsObjC/Inputs/comments-expected-output.h

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,84 @@ SWIFT_CLASS("_TtC8comments5Brief")
8686
@end
8787

8888

89+
SWIFT_CLASS("_TtC8comments16ClosureContainer")
90+
@interface ClosureContainer
91+
92+
/// Partially applies a binary operator.
93+
///
94+
/// \param a The left-hand side to partially apply.
95+
///
96+
/// \param combine A binary operator.
97+
///
98+
/// \a combine parameters:
99+
/// <ul>
100+
/// <li>
101+
/// lhs: The left-hand side of the operator
102+
///
103+
/// </li>
104+
/// <li>
105+
/// rhs: The right-hand side of the operator
106+
///
107+
/// </li>
108+
/// </ul>
109+
///
110+
///
111+
/// \a combine returns: A result.
112+
///
113+
/// \a combine error: Nothing.
114+
- (void)closureParameterExplodedExplodedWithA:(NSInteger)a combine:(NSInteger (^ _Nonnull)(NSInteger lhs, NSInteger rhs))combine;
115+
116+
/// Partially applies a binary operator.
117+
///
118+
/// \param a The left-hand side to partially apply.
119+
///
120+
/// \param combine A binary operator.
121+
///
122+
/// \a combine parameters:
123+
/// <ul>
124+
/// <li>
125+
/// lhs: The left-hand side of the operator
126+
///
127+
/// </li>
128+
/// <li>
129+
/// rhs: The right-hand side of the operator
130+
///
131+
/// </li>
132+
/// </ul>
133+
///
134+
///
135+
/// \a combine returns: A result.
136+
///
137+
/// \a combine error: Nothing.
138+
- (void)closureParameterOutlineExplodedWithA:(NSInteger)a combine:(NSInteger (^ _Nonnull)(NSInteger lhs, NSInteger rhs))combine;
139+
140+
/// Partially applies a binary operator.
141+
///
142+
/// \param a The left-hand side to partially apply.
143+
///
144+
/// \param combine A binary operator.
145+
///
146+
/// \a combine parameters:
147+
/// <ul>
148+
/// <li>
149+
/// lhs: The left-hand side of the operator
150+
///
151+
/// </li>
152+
/// <li>
153+
/// rhs: The right-hand side of the operator
154+
///
155+
/// </li>
156+
/// </ul>
157+
///
158+
///
159+
/// \a combine returns: A result.
160+
///
161+
/// \a combine error: Nothing.
162+
- (void)closureParameterOutlineOutlineWithA:(NSInteger)a combine:(NSInteger (^ _Nonnull)(NSInteger lhs, NSInteger rhs))combine;
163+
- (nonnull instancetype)init OBJC_DESIGNATED_INITIALIZER;
164+
@end
165+
166+
89167
SWIFT_CLASS("_TtC8comments9CodeBlock")
90168
@interface CodeBlock
91169

0 commit comments

Comments
 (0)