Merge pull request #2132 from bitjammer/closure-param-doc

Add nested parameter/returns/throws comment recognition

Author: bitjammer

bindings/xml/comment-xml-schema.rng

@@ -650,9 +650,28 @@
           <!-- In general, template parameters with whitespace discussion
                should not be emitted, unless direction is explicitly specified.
                Schema might be more strict here. -->
-          <element name="Discussion">
-            <ref name="BlockContent" />
-          </element>
+          <choice>
+            <element name="ClosureParameter">
+              <optional>
+                <ref name="Abstract" />
+              </optional>
+              <optional>
+                <ref name="Parameters" />
+              </optional>
+              <optional>
+                <ref name="ResultDiscussion" />
+              </optional>
+              <optional>
+                <ref name="ThrowsDiscussion" />
+              </optional>
+              <optional>
+                <ref name="Discussion" />
+              </optional>
+            </element>
+            <element name="Discussion">
+              <ref name="BlockContent" />
+            </element>
+          </choice>
         </element>
       </oneOrMore>
     </element>

include/swift/AST/Comment.h

@@ -22,54 +22,40 @@ class DocComment;
 struct RawComment;
 
 class DocComment {
-public:
-  struct CommentParts {
-    Optional<const llvm::markup::Paragraph *>Brief;
-    ArrayRef<const llvm::markup::MarkupASTNode *> BodyNodes;
-    ArrayRef<const llvm::markup::ParamField *> ParamFields;
-    Optional<const llvm::markup::ReturnsField *> ReturnsField;
-    Optional<const llvm::markup::ThrowsField *> ThrowsField;
-
-    bool isEmpty() const {
-      return !Brief.hasValue() && !ReturnsField.hasValue() && !ThrowsField.hasValue() && BodyNodes.empty() && ParamFields.empty();
-    }
-  };
-
-private:
   const Decl *D;
-  const llvm::markup::Document *Doc = nullptr;
-  const CommentParts Parts;
+  const swift::markup::Document *Doc = nullptr;
+  const swift::markup::CommentParts Parts;
 
 public:
-  DocComment(const Decl *D, llvm::markup::Document *Doc,
-             CommentParts Parts)
+  DocComment(const Decl *D, swift::markup::Document *Doc,
+             swift::markup::CommentParts Parts)
       : D(D), Doc(Doc), Parts(Parts) {}
 
   const Decl *getDecl() const { return D; }
 
-  const llvm::markup::Document *getDocument() const { return Doc; }
+  const swift::markup::Document *getDocument() const { return Doc; }
 
-  CommentParts getParts() const {
+  swift::markup::CommentParts getParts() const {
     return Parts;
   }
 
-  Optional<const llvm::markup::Paragraph *> getBrief() const {
+  Optional<const swift::markup::Paragraph *> getBrief() const {
     return Parts.Brief;
   }
 
-  Optional<const llvm::markup::ReturnsField * >getReturnsField() const {
+  Optional<const swift::markup::ReturnsField * >getReturnsField() const {
     return Parts.ReturnsField;
   }
 
-  Optional<const llvm::markup::ThrowsField*> getThrowsField() const {
+  Optional<const swift::markup::ThrowsField*> getThrowsField() const {
     return Parts.ThrowsField;
   }
 
-  ArrayRef<const llvm::markup::ParamField *> getParamFields() const {
+  ArrayRef<const swift::markup::ParamField *> getParamFields() const {
     return Parts.ParamFields;
   }
 
-  ArrayRef<const llvm::markup::MarkupASTNode *> getBodyNodes() const {
+  ArrayRef<const swift::markup::MarkupASTNode *> getBodyNodes() const {
     return Parts.BodyNodes;
   }
 
@@ -79,7 +65,7 @@ class DocComment {
 
   // Only allow allocation using the allocator in MarkupContext or by
   // placement new.
-  void *operator new(size_t Bytes, llvm::markup::MarkupContext &MC,
+  void *operator new(size_t Bytes, swift::markup::MarkupContext &MC,
                      unsigned Alignment = alignof(DocComment));
   void *operator new(size_t Bytes, void *Mem) {
     assert(Mem);
@@ -91,7 +77,7 @@ class DocComment {
   void operator delete(void *Data) = delete;
 };
 
-Optional<DocComment *>getDocComment(llvm::markup::MarkupContext &Context,
+Optional<DocComment *>getDocComment(swift::markup::MarkupContext &Context,
                                     const Decl *D);
 
 } // namespace swift

include/swift/Markup/AST.h

@@ -10,18 +10,47 @@
 //
 //===----------------------------------------------------------------------===//
 //
-#ifndef LLVM_MARKUP_AST_H
-#define LLVM_MARKUP_AST_H
+#ifndef SWIFT_MARKUP_AST_H
+#define SWIFT_MARKUP_AST_H
 
 #include "swift/Markup/LineList.h"
 #include "llvm/ADT/Optional.h"
 #include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/TrailingObjects.h"
 
-namespace llvm {
+namespace swift {
 namespace markup {
 
 class MarkupContext;
+class MarkupASTNode;
+class Paragraph;
+class ParamField;
+class ReturnsField;
+class ThrowsField;
+
+/// The basic structure of a doc comment attached to a Swift
+/// declaration.
+struct CommentParts {
+  Optional<const Paragraph *> Brief;
+  ArrayRef<const MarkupASTNode *> BodyNodes;
+  ArrayRef<ParamField *> ParamFields;
+  Optional<const ReturnsField *> ReturnsField;
+  Optional<const ThrowsField *> ThrowsField;
+
+  bool isEmpty() const {
+    return !Brief.hasValue() &&
+           !ReturnsField.hasValue() &&
+           !ThrowsField.hasValue() &&
+           BodyNodes.empty() &&
+           ParamFields.empty();
+  }
+
+  bool hasFunctionDocumentation() const {
+    return !ParamFields.empty() ||
+             ReturnsField.hasValue() ||
+             ThrowsField.hasValue();
+  }
+};
 
 #define MARKUP_AST_NODE(Id, Parent) class Id;
 #define ABSTRACT_MARKUP_AST_NODE(Id, Parent) class Id;
@@ -585,6 +614,10 @@ class ParamField final : public PrivateExtension,
 
   StringRef Name;
 
+  // Parameter fields can contain a substructure describing a
+  // function or closure parameter.
+  llvm::Optional<CommentParts> Parts;
+
   ParamField(StringRef Name, ArrayRef<MarkupASTNode *> Children);
 
 public:
@@ -596,6 +629,21 @@ class ParamField final : public PrivateExtension,
     return Name;
   }
 
+  llvm::Optional<CommentParts> getParts() const {
+    return Parts;
+  }
+
+  void setParts(CommentParts P) {
+    Parts = P;
+  }
+
+  bool isClosureParameter() const {
+    if (!Parts.hasValue())
+      return false;
+
+    return Parts.getValue().hasFunctionDocumentation();
+  }
+
   ArrayRef<MarkupASTNode *> getChildren() {
     return {getTrailingObjects<MarkupASTNode *>(), NumChildren};
   }
@@ -682,6 +730,6 @@ void dump(const MarkupASTNode *Node, llvm::raw_ostream &OS, unsigned indent = 0)
 void printInlinesUnder(const MarkupASTNode *Node, llvm::raw_ostream &OS,
                        bool PrintDecorators = false);
 } // namespace markup
-} // namespace llvm
+} // namespace swift
 
-#endif // LLVM_MARKUP_AST_H
+#endif // SWIFT_MARKUP_AST_H

include/swift/Markup/LineList.h

@@ -10,14 +10,14 @@
 //
 //===----------------------------------------------------------------------===//
 
-#ifndef LLVM_MARKUP_LINELIST_H
-#define LLVM_MARKUP_LINELIST_H
+#ifndef SWIFT_MARKUP_LINELIST_H
+#define SWIFT_MARKUP_LINELIST_H
 
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/StringRef.h"
 #include "swift/Basic/SourceLoc.h"
 
-namespace llvm {
+namespace swift {
 namespace markup {
 
 class MarkupContext;
@@ -76,6 +76,6 @@ class LineListBuilder {
 };
 
 } // namespace markup
-} // namespace llvm
+} // namespace swift
 
-#endif // LLVM_MARKUP_LINELIST_H
+#endif // SWIFT_MARKUP_LINELIST_H

include/swift/Markup/Markup.h

@@ -10,8 +10,8 @@
 //
 //===----------------------------------------------------------------------===//
 
-#ifndef LLVM_MARKUP_MARKUP_H
-#define LLVM_MARKUP_MARKUP_H
+#ifndef SWIFT_MARKUP_MARKUP_H
+#define SWIFT_MARKUP_MARKUP_H
 
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/Support/Allocator.h"
@@ -20,12 +20,10 @@
 #include "swift/Markup/AST.h"
 #include "swift/Markup/LineList.h"
 
-
 namespace swift {
-  struct RawComment;
-}
 
-namespace llvm {
+struct RawComment;
+
 namespace markup {
 
 class LineList;
@@ -65,6 +63,6 @@ class MarkupContext final {
 Document *parseDocument(MarkupContext &MC, LineList &LL);
 
 } // namespace markup
-} // namespace llvm
+} // namespace swift
 
-#endif // LLVM_MARKUP_MARKUP_H
+#endif // SWIFT_MARKUP_MARKUP_H

include/swift/Markup/SourceLoc.h

@@ -11,16 +11,16 @@
 //===----------------------------------------------------------------------===//
 
 
-#ifndef LLVM_REST_SOURCELOC_H
-#define LLVM_REST_SOURCELOC_H
+#ifndef SWIFT_MARKUP_SOURCELOC_H
+#define SWIFT_MARKUP_SOURCELOC_H
 
 #include "llvm/ADT/StringRef.h"
 #include <algorithm>
 #include <cassert>
 #include <utility>
 #include <vector>
 
-namespace llvm {
+namespace swift {
 namespace markup {
 
 class SourceLoc {
@@ -147,7 +147,7 @@ SourceManager<ExternalSourceLocTy>::toExternalSourceLoc(SourceLoc Loc) const {
 }
 
 } // namespace markup
-} // namespace llvm
+} // namespace swift
 
-#endif // LLVM_REST_SOURCELOC_H
+#endif // SWIFT_MARKUP_SOURCELOC_H
 

include/swift/Markup/XMLUtils.h

@@ -10,13 +10,13 @@
 //
 //===----------------------------------------------------------------------===//
 
-#ifndef LLVM_MARKUP_XML_UTILS_H
-#define LLVM_MARKUP_XML_UTILS_H
+#ifndef SWIFT_MARKUP_XML_UTILS_H
+#define SWIFT_MARKUP_XML_UTILS_H
 
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/raw_ostream.h"
 
-namespace llvm {
+namespace swift {
 namespace markup {
 
 // FIXME: copied from Clang's
@@ -71,7 +71,7 @@ static inline void appendWithCDATAEscaping(raw_ostream &OS, StringRef S) {
 }
 
 } // namespace markup
-} // namespace llvm
+} // namespace swift
 
-#endif // LLVM_MARKUP_XML_UTILS_H
+#endif // SWIFT_MARKUP_XML_UTILS_H