generate multiline doc comments

banjun · Apr 10, 2017 · 87f01c5 · 87f01c5
1 parent 21c5fcb
commit 87f01c5
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 18 deletions.
diff --git a/Examples/01. Simplest API.swift b/Examples/01. Simplest API.swift
@@ -51,7 +51,7 @@ struct TextBodyParameters: BodyParameters {
 
 // MARK: - Transitions
 
-/// 
+
 struct GET__message: Request {
     typealias Response = Responses
     let baseURL: URL

diff --git a/Examples/02. Resource and Actions.swift b/Examples/02. Resource and Actions.swift
@@ -52,12 +52,12 @@ struct TextBodyParameters: BodyParameters {
 // MARK: - Transitions
 
 /// Here we define an action using the `GET` [HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`.
-
-As with every good action it should return a
-[response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always
-bears a status code. Code 200 is great as it means all is green. Responding
-with some data can be a great idea as well so let's add a plain text message to
-our response.
+/// 
+/// As with every good action it should return a
+/// [response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always
+/// bears a status code. Code 200 is great as it means all is green. Responding
+/// with some data can be a great idea as well so let's add a plain text message to
+/// our response.
 struct GET__message: Request {
     typealias Response = Responses
     let baseURL: URL
@@ -99,10 +99,10 @@ struct GET__message: Request {
 }
 
 /// OK, let's add another action. This time to put new data to our resource
-(essentially an update action). We will need to send something in a
-[request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a
-response back confirming the posting was a success (_HTTP Status Code 204 ~
-Resource updated successfully, no content is returned_).
+/// (essentially an update action). We will need to send something in a
+/// [request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a
+/// response back confirming the posting was a success (_HTTP Status Code 204 ~
+/// Resource updated successfully, no content is returned_).
 struct PUT__message: Request {
     typealias Response = Responses
     let baseURL: URL

diff --git a/Sources/Generator.swift b/Sources/Generator.swift
@@ -32,12 +32,16 @@ fileprivate extension String {
         let cs = CharacterSet(charactersIn: " _/{?,}-")
         return components(separatedBy: cs).joined(separator: "_")
     }
+
+    func docCommentPrefixed() -> String {
+        return components(separatedBy: .newlines).map {"/// " + $0}.joined(separator: "\n")
+    }
 }
 
 extension APIBlueprintDataStructure: SwiftConvertible {
     func swift(_ name: String? = nil) throws -> SwiftCode {
         let localDSTemplate = Template(templateString: ["struct {{ name }} { {% for v in vars %}",
-                                                        "    /// {{ v.doc }}",
+                                                        "    {{ v.doc }}",
                                                         "    var {{ v.name }}: {{ v.type }}{% endfor %}",
                                                         "}\n"].joined(separator: "\n"))
         let globalDSTemplate = Template(templateString: ["extension {{ fqn }}: Decodable {",
@@ -90,7 +94,7 @@ extension APIBlueprintTransition: SwiftConvertible {
                 .flatMap {$0.transaction.responses}
         }
 
-        let trTemplate = Template(templateString: ["/// {{ copy }}",
+        let trTemplate = Template(templateString: ["{{ copy }}",
                                                    "struct {{ name }}: Request {",
                                                    "    typealias Response = {{ response }}",
                                                    "    let baseURL: URL",
@@ -100,7 +104,7 @@ extension APIBlueprintTransition: SwiftConvertible {
                                                    "    static let pathTemplate: URITemplate = \"{{ path }}\"",
                                                    "    var pathVars: PathVars",
                                                    "    struct PathVars {",
-                                                   "{% endif %}        /// {{ v.doc }}",
+                                                   "{% endif %}        {{ v.doc }}",
                                                    "        var {{ v.name }}: {{ v.type }}",
                                                    "{% if forloop.last %}    }",
                                                    "{% endif %}{% empty %}",
@@ -118,7 +122,7 @@ extension APIBlueprintTransition: SwiftConvertible {
                                                    "    var headerFields: [String: String] {return headerVars.context as? [String: String] ?? [:]}",
                                                    "    var headerVars: HeaderVars",
                                                    "    struct HeaderVars {",
-                                                   "{% for v in headerVars %}       /// {{ v.doc }}",
+                                                   "{% for v in headerVars %}       {{ v.doc }}",
                                                    "        var {{ v.name }}: {{ v.type }}",
                                                    "{% endfor %}",
                                                    "    }",
@@ -228,7 +232,7 @@ extension APIBlueprintTransition: SwiftConvertible {
                 ["key": k,
                  "name": k.lowercased().swiftIdentifierized(),
                  "type": "String",
-                 "doc": v]
+                 "doc": v.docCommentPrefixed()]
             }
             context["headerVars"] = headerVars
             globalExtensionCode += try globalPathVarsTemplate.render([
@@ -255,7 +259,7 @@ extension APIBlueprintTransition: SwiftConvertible {
                 context["paramContentType"] = requestContentType
             }
         }
-        context["copy"] = copy?.text
+        context["copy"] = copy?.text.docCommentPrefixed()
 
         return try (local: trTemplate.render(context), global: globalExtensionCode)
     }
@@ -282,5 +286,8 @@ extension APIBlueprintMember {
         }
         return name + (required ? "" : "?")
     }
-    var swiftDoc: String {return [meta?.description, content.displayValue.map {" ex. " + $0}].flatMap {$0}.joined(separator: " ")}
+    var swiftDoc: String {return [meta?.description, content.displayValue.map {" ex. " + $0}]
+        .flatMap {$0}
+        .joined(separator: " ")
+        .docCommentPrefixed()}
 }