From 705776517bc3e1b5412183e22e5fd0e5b1782c88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= <miroslav@strongloop.com>
Date: Mon, 13 Oct 2014 19:32:09 +0200
Subject: [PATCH] Support multi-line array `description` and `notes`

When a string value is expected and the user supplied an array,
convert the value to a single string by joining all array items.
---
 lib/class-helper.js       |  7 +++++--
 lib/route-helper.js       | 18 +++++++++++++++---
 test/class-helper.test.js | 23 +++++++++++++++++++++++
 test/route-helper.test.js | 21 +++++++++++++++++++++
 4 files changed, 64 insertions(+), 5 deletions(-)
 create mode 100644 test/class-helper.test.js

diff --git a/lib/class-helper.js b/lib/class-helper.js
index 860e008..1e9c128 100644
--- a/lib/class-helper.js
+++ b/lib/class-helper.js
@@ -4,6 +4,7 @@
  * Module dependencies.
  */
 var modelHelper = require('./model-helper');
+var routeHelper = require('./route-helper');
 var urlJoin = require('./url-join');
 
 /**
@@ -41,10 +42,12 @@ var classHelper = module.exports = {
    * @return {Object}       API declaration reference.
    */
   generateResourceDocAPIEntry: function(aClass) {
+    var description = aClass.ctor.settings.description ||
+      aClass.ctor.sharedCtor && aClass.ctor.sharedCtor.description;
+
     return {
       path: aClass.http.path,
-      description: aClass.ctor.settings.description ||
-        aClass.ctor.sharedCtor && aClass.ctor.sharedCtor.description
+      description: routeHelper.convertText(description)
     };
   }
 };
diff --git a/lib/route-helper.js b/lib/route-helper.js
index b47b850..6cf5b4a 100644
--- a/lib/route-helper.js
+++ b/lib/route-helper.js
@@ -137,8 +137,8 @@ var routeHelper = module.exports = {
         parameters: accepts,
         // TODO(schoon) - We don't have descriptions for this yet.
         responseMessages: [], 
-        summary: route.description,
-        notes: route.notes,
+        summary: routeHelper.convertText(route.description),
+        notes: routeHelper.convertText(route.notes),
         deprecated: route.deprecated
       })]
     };
@@ -195,7 +195,7 @@ var routeHelper = module.exports = {
       var out = {
         paramType: paramType || type,
         name: name,
-        description: accepts.description,
+        description: routeHelper.convertText(accepts.description),
         type: accepts.type,
         required: !!accepts.required,
         defaultValue: accepts.defaultValue,
@@ -234,6 +234,18 @@ var routeHelper = module.exports = {
       obj[key] = typeDesc[key];
     });
     return obj;
+  },
+
+  /**
+   * Convert a text value that can be expressed either as a string or
+   * as an array of strings.
+   * @param {string|Array} value
+   * @returns {string}
+   */
+  convertText: function(value) {
+    if (Array.isArray(value))
+      return value.join('\n');
+    return value;
   }
 };
 
diff --git a/test/class-helper.test.js b/test/class-helper.test.js
new file mode 100644
index 0000000..beb6d8f
--- /dev/null
+++ b/test/class-helper.test.js
@@ -0,0 +1,23 @@
+'use strict';
+
+var classHelper = require('../lib/class-helper');
+var expect = require('chai').expect;
+var _defaults = require('lodash.defaults');
+
+describe('class-helper', function() {
+  it('joins array descriptions', function() {
+    var doc = generateResourceDocAPIEntry({
+      ctor: { settings: { description: [ 'line1', 'line2' ] } }
+    });
+
+    expect(doc.description).to.equal('line1\nline2');
+  });
+});
+
+// Easy wrapper around createRoute
+function generateResourceDocAPIEntry(def) {
+  return classHelper.generateResourceDocAPIEntry(_defaults(def, {
+    http: { path: '/test' },
+    ctor: { settings: { } },
+  }));
+}
diff --git a/test/route-helper.test.js b/test/route-helper.test.js
index a25d993..52e21b8 100644
--- a/test/route-helper.test.js
+++ b/test/route-helper.test.js
@@ -88,6 +88,27 @@ describe('route-helper', function() {
     });
     expect(doc.operations[0].deprecated).to.equal('true');
   });
+
+  it('joins array description/summary', function() {
+    var doc = createAPIDoc({
+      description: [ 'line1', 'line2' ]
+    });
+    expect(doc.operations[0].summary).to.equal('line1\nline2');
+  });
+
+  it('joins array notes', function() {
+    var doc = createAPIDoc({
+      notes: [ 'line1', 'line2' ]
+    });
+    expect(doc.operations[0].notes).to.equal('line1\nline2');
+  });
+
+  it('joins array description/summary of an input arg', function() {
+    var doc = createAPIDoc({
+      accepts: [{ name: 'arg', description: [ 'line1', 'line2' ] }]
+    });
+    expect(doc.operations[0].parameters[0].description).to.equal('line1\nline2');
+  });
 });
 
 // Easy wrapper around createRoute