Add a Requires field to doc comments

rdar://problem/20902140

Swift SVN r28446

Author: bitjammer

bindings/xml/comment-xml-schema.rng

@@ -507,6 +507,14 @@
     </element>
   </define>
 
+  <define name="Requires">
+    <element name="Requires">
+      <zeroOrMore>
+        <ref name="BlockContent"/>
+      </zeroOrMore>
+    </element>
+  </define>
+
   <define name="See">
     <element name="See">
       <zeroOrMore>
@@ -715,6 +723,7 @@
       <ref name="Precondition"/>
       <ref name="Remark"/>
       <ref name="Remarks"/>
+      <ref name="Requires"/>
       <ref name="See"/>
       <ref name="Since"/>
       <ref name="TODO"/>

docs/DocumentationComments.rst

@@ -80,6 +80,7 @@ one is supported and appear in order inside QuickHelp.
   - Precondition: ...
   - Remark: ...
   - Remarks: ...
+  - Requires: ...
   - See: ...
   - Since: ...
   - Todo: ...

include/swift/Markup/ASTNodes.def

@@ -67,6 +67,7 @@ MARKUP_AST_NODE(PrivateExtension, MarkupASTNode)
   MARKUP_AST_NODE(RemarkField, PrivateExtension)
   MARKUP_AST_NODE(RemarksField, PrivateExtension)
   MARKUP_AST_NODE(ReturnsField, PrivateExtension)
+  MARKUP_AST_NODE(RequiresField, PrivateExtension)
   MARKUP_AST_NODE(SeeField, PrivateExtension)
   MARKUP_AST_NODE(SinceField, PrivateExtension)
   MARKUP_AST_NODE(TODOField, PrivateExtension)

include/swift/Markup/SimpleFields.def

@@ -37,6 +37,7 @@ MARKUP_SIMPLE_FIELD(PreconditionField, precondition, Precondition)
 MARKUP_SIMPLE_FIELD(RemarkField, remark, Remark)
 MARKUP_SIMPLE_FIELD(RemarksField, remarks, Remarks)
 MARKUP_SIMPLE_FIELD(ReturnsField, returns, Returns)
+MARKUP_SIMPLE_FIELD(RequiresField, requires, Requires)
 MARKUP_SIMPLE_FIELD(SeeField, seealso, See)
 MARKUP_SIMPLE_FIELD(SinceField, since, Since)
 MARKUP_SIMPLE_FIELD(TODOField, todo, TODO)

test/IDE/comment_extensions.swift

@@ -67,6 +67,11 @@ func remark() {}
 func remarks() {}
 // CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>remarks()</Name><USR>s:F14swift_ide_test7remarksFT_T_</USR><Declaration>func remarks()</Declaration><Discussion><Remarks><Para></Para><List-Bullet><Item><Para>Never let a bear approach you.</Para></Item></List-Bullet></Remarks></Discussion></Function>]
 
+/// - requires:
+///   - explicit package name. Just kidding!
+func requires() {}
+// CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>requires()</Name><USR>s:F14swift_ide_test8requiresFT_T_</USR><Declaration>func requires()</Declaration><Discussion><Requires><Para></Para><List-Bullet><Item><Para>explicit package name. Just kidding!</Para></Item></List-Bullet></Requires></Discussion></Function>]
+
 /// - seealso: the pie (it's very good).
 func see() {}
 // CHECK: {{.*}}DocCommentAsXML=[<Function file="{{.*}}" line="{{.*}}" column="{{.*}}"><Name>see()</Name><USR>s:F14swift_ide_test3seeFT_T_</USR><Declaration>func see()</Declaration><Discussion><See><Para>the pie (it&apos;s very good).</Para></See></Discussion></Function>]