From b29220a27e5ce190633c57627e9658c6dc6645a8 Mon Sep 17 00:00:00 2001
From: David Farler <dfarler@apple.com>
Date: Mon, 11 May 2015 22:52:34 +0000
Subject: [PATCH] Add a Requires field to doc comments

rdar://problem/20902140

Swift SVN r28446
---
 bindings/xml/comment-xml-schema.rng   | 9 +++++++++
 docs/DocumentationComments.rst        | 1 +
 include/swift/Markup/ASTNodes.def     | 1 +
 include/swift/Markup/SimpleFields.def | 1 +
 test/IDE/comment_extensions.swift     | 5 +++++
 5 files changed, 17 insertions(+)

diff --git a/bindings/xml/comment-xml-schema.rng b/bindings/xml/comment-xml-schema.rng
index 91de35fb48e..c4d68119504 100644
--- a/bindings/xml/comment-xml-schema.rng
+++ b/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"/>
diff --git a/docs/DocumentationComments.rst b/docs/DocumentationComments.rst
index 049eee2bcc4..1c889b78d00 100644
--- a/docs/DocumentationComments.rst
+++ b/docs/DocumentationComments.rst
@@ -80,6 +80,7 @@ one is supported and appear in order inside QuickHelp.
   - Precondition: ...
   - Remark: ...
   - Remarks: ...
+  - Requires: ...
   - See: ...
   - Since: ...
   - Todo: ...
diff --git a/include/swift/Markup/ASTNodes.def b/include/swift/Markup/ASTNodes.def
index 2e591967ecc..1bd1cc97a4f 100644
--- a/include/swift/Markup/ASTNodes.def
+++ b/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)
diff --git a/include/swift/Markup/SimpleFields.def b/include/swift/Markup/SimpleFields.def
index 73faa0a4a53..f74cf2ce02e 100644
--- a/include/swift/Markup/SimpleFields.def
+++ b/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)
diff --git a/test/IDE/comment_extensions.swift b/test/IDE/comment_extensions.swift
index eb356d2219c..9e253fd9193 100644
--- a/test/IDE/comment_extensions.swift
+++ b/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>]