Skip to content

Commit dd44dad

Browse files
bitjammerbitjammer
committed
Add 'throws' keyword to doc comments
Adding the following to a doc comment: - throws: ... Will create a description about what/when the function will throw. This should be a peer to "- returns:" and "- parameter:" and not appear inline in the description. rdar://problem/21621679 Swift SVN r29831
1 parent 7b98fbf commit dd44dad

9 files changed

+102
-5
lines changed

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

+29
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@
3939
<optional>
4040
<ref name="Parameters" />
4141
</optional>
42+
<optional>
43+
<ref name="ThrowsDiscussion" />
44+
</optional>
4245
<optional>
4346
<ref name="ResultDiscussion" />
4447
</optional>
@@ -102,6 +105,9 @@
102105
<zeroOrMore>
103106
<ref name="Unavailable" />
104107
</zeroOrMore>
108+
<optional>
109+
<ref name="ThrowsDiscussion" />
110+
</optional>
105111
<optional>
106112
<ref name="ResultDiscussion" />
107113
</optional>
@@ -146,6 +152,9 @@
146152
<optional>
147153
<ref name="Parameters" />
148154
</optional>
155+
<optional>
156+
<ref name="ThrowsDiscussion" />
157+
</optional>
149158
<optional>
150159
<ref name="ResultDiscussion" />
151160
</optional>
@@ -182,6 +191,9 @@
182191
<optional>
183192
<ref name="Parameters" />
184193
</optional>
194+
<optional>
195+
<ref name="ThrowsDiscussion" />
196+
</optional>
185197
<optional>
186198
<ref name="ResultDiscussion" />
187199
</optional>
@@ -218,6 +230,9 @@
218230
<optional>
219231
<ref name="Parameters" />
220232
</optional>
233+
<optional>
234+
<ref name="ThrowsDiscussion" />
235+
</optional>
221236
<optional>
222237
<ref name="ResultDiscussion" />
223238
</optional>
@@ -254,6 +269,9 @@
254269
<optional>
255270
<ref name="Parameters" />
256271
</optional>
272+
<optional>
273+
<ref name="ThrowsDiscussion" />
274+
</optional>
257275
<optional>
258276
<ref name="ResultDiscussion" />
259277
</optional>
@@ -290,6 +308,9 @@
290308
<optional>
291309
<ref name="Parameters" />
292310
</optional>
311+
<optional>
312+
<ref name="ThrowsDiscussion" />
313+
</optional>
293314
<optional>
294315
<ref name="ResultDiscussion" />
295316
</optional>
@@ -698,6 +719,14 @@
698719
</element>
699720
</define>
700721

722+
<define name="ThrowsDiscussion">
723+
<element name="ThrowsDiscussion">
724+
<zeroOrMore>
725+
<ref name="BlockContent" />
726+
</zeroOrMore>
727+
</element>
728+
</define>
729+
701730
<define name="ResultDiscussion">
702731
<element name="ResultDiscussion">
703732
<zeroOrMore>

‎docs/DocumentationComments.rst

+10
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,16 @@ shown in Xcode's QuickHelp.
5656

5757
- returns: ...
5858

59+
Throwing Functions
60+
------------------
61+
62+
Functions that are marked as `throws` should contain the following describing
63+
what kind of errors are thrown and in what situations:
64+
65+
::
66+
67+
- throws: ...
68+
5969

6070
Field Extensions
6171
----------------

‎include/swift/AST/Comment.h

+9-4
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,11 @@ class DocComment {
2727
Optional<const llvm::markup::Paragraph *>Brief;
2828
SmallVector<const llvm::markup::MarkupASTNode *, 4> BodyNodes;
2929
SmallVector<const llvm::markup::ParamField *, 8> ParamFields;
30-
Optional<const llvm::markup::ReturnsField *>ReturnsField;
30+
Optional<const llvm::markup::ReturnsField *> ReturnsField;
31+
Optional<const llvm::markup::ThrowsField *> ThrowsField;
3132

3233
bool isEmpty() const {
33-
return !Brief.hasValue() && !ReturnsField.hasValue() && BodyNodes.empty() && ParamFields.empty();
34+
return !Brief.hasValue() && !ReturnsField.hasValue() && !ThrowsField.hasValue() && BodyNodes.empty() && ParamFields.empty();
3435
}
3536
};
3637

@@ -52,14 +53,18 @@ class DocComment {
5253
return Parts;
5354
}
5455

55-
Optional<const llvm::markup::Paragraph *>getBrief() const {
56+
Optional<const llvm::markup::Paragraph *> getBrief() const {
5657
return Parts.Brief;
5758
}
5859

59-
Optional<const llvm::markup::ReturnsField *>getReturnsField() const {
60+
Optional<const llvm::markup::ReturnsField * >getReturnsField() const {
6061
return Parts.ReturnsField;
6162
}
6263

64+
Optional<const llvm::markup::ThrowsField*> getThrowsField() const {
65+
return Parts.ThrowsField;
66+
}
67+
6368
ArrayRef<const llvm::markup::ParamField *> getParamFields() const {
6469
return Parts.ParamFields;
6570
}

‎include/swift/Markup/ASTNodes.def

+1
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ MARKUP_AST_NODE(PrivateExtension, MarkupASTNode)
7171
MARKUP_AST_NODE(SeeField, PrivateExtension)
7272
MARKUP_AST_NODE(SinceField, PrivateExtension)
7373
MARKUP_AST_NODE(TODOField, PrivateExtension)
74+
MARKUP_AST_NODE(ThrowsField, PrivateExtension)
7475
MARKUP_AST_NODE(VersionField, PrivateExtension)
7576
MARKUP_AST_NODE(WarningField, PrivateExtension)
7677

‎include/swift/Markup/SimpleFields.def

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ MARKUP_SIMPLE_FIELD(PreconditionField, precondition, Precondition)
3737
MARKUP_SIMPLE_FIELD(RemarkField, remark, Remark)
3838
MARKUP_SIMPLE_FIELD(RemarksField, remarks, Remarks)
3939
MARKUP_SIMPLE_FIELD(ReturnsField, returns, Returns)
40+
MARKUP_SIMPLE_FIELD(ThrowsField, throws, Throws)
4041
MARKUP_SIMPLE_FIELD(RequiresField, requires, Requires)
4142
MARKUP_SIMPLE_FIELD(SeeField, seealso, See)
4243
MARKUP_SIMPLE_FIELD(SinceField, since, Since)

‎lib/AST/DocComment.cpp

+2
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,8 @@ bool extractSimpleField(llvm::markup::MarkupContext &MC,
261261

262262
if (auto RF = dyn_cast<llvm::markup::ReturnsField>(Field))
263263
Parts.ReturnsField = RF;
264+
else if (auto TF = dyn_cast<llvm::markup::ThrowsField>(Field))
265+
Parts.ThrowsField = TF;
264266
else
265267
Parts.BodyNodes.push_back(Field);
266268
}

‎lib/IDE/CommentConversion.cpp

+25
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,13 @@ struct CommentToXMLConverter {
210210
OS << "</ResultDiscussion>";
211211
}
212212

213+
void printThrowsDiscussion(const ThrowsField *RF) {
214+
OS << "<ThrowsDiscussion>";
215+
for (auto Child : RF->getChildren())
216+
printASTNode(Child);
217+
OS << "</ThrowsDiscussion>";
218+
}
219+
213220
void visitDocComment(const DocComment *DC);
214221
};
215222
} // unnamed namespace
@@ -307,6 +314,10 @@ void CommentToXMLConverter::visitDocComment(const DocComment *DC) {
307314
if (RF.hasValue())
308315
printResultDiscussion(RF.getValue());
309316

317+
auto TF = DC->getThrowsField();
318+
if (TF.hasValue())
319+
printThrowsDiscussion(TF.getValue());
320+
310321
if (!DC->getBodyNodes().empty()) {
311322
OS << "<Discussion>";
312323
for (const auto *N : DC->getBodyNodes())
@@ -554,6 +565,14 @@ break;
554565

555566
printNewline();
556567
}
568+
569+
void printThrowField(const ThrowsField *TF) {
570+
print("\\param error ");
571+
for (auto Child : TF->getChildren())
572+
printASTNode(Child);
573+
574+
printNewline();
575+
}
557576
};
558577
} // unnamed namespace
559578

@@ -587,6 +606,12 @@ void ide::getDocumentationCommentAsDoxygen(const DocComment *DC,
587606
Converter.printNewline();
588607
}
589608

609+
auto TF = DC->getThrowsField();
610+
if (TF.hasValue()) {
611+
Converter.printThrowField(TF.getValue());
612+
Converter.printNewline();
613+
}
614+
590615
auto RF = DC->getReturnsField();
591616
if (RF.hasValue()) {
592617
Converter.printReturnField(RF.getValue());

‎test/Inputs/comment_to_something_conversion.swift

+11-1
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,17 @@ enum A012_AttachToEntities {
153153
// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>f0()</Name><USR>s:FC14swift_ide_test8Emphasis2f0FS0_FT_T_</USR><Declaration>func f0()</Declaration><Abstract><Para>Aaa <emphasis>bbb</emphasis> ccc. Aaa <emphasis>bbb</emphasis> ccc.</Para></Abstract></Function>]
154154
}
155155

156+
@objc class HasThrowingFunction {
157+
// CHECK: {{.*}}DocCommentAsXML=none
158+
159+
/// Might throw something.
160+
///
161+
/// - parameter x: A number
162+
/// - throws: An error if `x == 0`
163+
@objc func f1(x: Int) /*throws*/ {}
164+
// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>f1(_:)</Name><USR>s:FC14swift_ide_test19HasThrowingFunction2f1FS0_FSiT_</USR><Declaration>@objc func f1(x: Int)</Declaration><Abstract><Para>Might throw something.</Para></Abstract><Parameters><Parameter><Name>x</Name><Direction isExplicit="0">in</Direction><Discussion><Para>A number</Para></Discussion></Parameter></Parameters><ThrowsDiscussion><Para>An error if <codeVoice>x == 0</codeVoice></Para></ThrowsDiscussion></Function>]
165+
}
166+
156167
@objc class HorizontalRules {
157168
// CHECK: {{.*}}DocCommentAsXML=none
158169
/// Briefly.
@@ -394,4 +405,3 @@ func f0(x: Int, y: Int, z: Int) {}
394405
func f0() {}
395406
// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>f0()</Name><USR>s:FC14swift_ide_test14MultiLineBrief2f0FS0_FT_T_</USR><Declaration>func f0()</Declaration><Abstract><Para>Brief first line. Brief after softbreak.</Para></Abstract><Discussion><Para>Some paragraph text.</Para></Discussion></Function>]
396407
}
397-

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

+14
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,20 @@ SWIFT_CLASS("_TtC8comments13EmptyComments")
128128
@end
129129

130130

131+
SWIFT_CLASS("_TtC8comments19HasThrowingFunction")
132+
@interface HasThrowingFunction
133+
134+
/// Might throw something.
135+
///
136+
/// \param x A number
137+
///
138+
/// \param error An error if <code>x == 0
139+
/// </code>
140+
- (void)f1:(NSInteger)x;
141+
- (nonnull instancetype)init OBJC_DESIGNATED_INITIALIZER;
142+
@end
143+
144+
131145
SWIFT_CLASS("_TtC8comments15HorizontalRules")
132146
@interface HorizontalRules
133147

0 commit comments

Comments
 (0)