Merge pull request #59 from strongloop/feature/support-array-descriptions

Support multi-line array `description` and `notes`

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)
     };
   }
 };

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;
   }
 };
 

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: { } },
+  }));
+}

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