added sort-by option, output sorted by default

Author: 75lb

es5/jsdoc-parse.js

@@ -21,5 +21,16 @@ function parse(jsdocData, options) {
     }
   });
 
+  data = sort(data, options['sort-by']);
   return data;
+}
+
+function sort(array, properties) {
+  var sortBy = require('sort-array');
+  var customOrder = {
+    kind: ['class', 'constructor', 'mixin', 'member', 'namespace', 'enum', 'constant', 'function', 'event', 'typedef', 'external'],
+    scope: ['global', 'instance', 'static', 'inner']
+  };
+  properties = properties || ['scope', 'category', 'kind', 'order'];
+  return sortBy(array, properties, customOrder);
 }

lib/jsdoc-parse.js

@@ -4,23 +4,25 @@ const transform = require('./transform')
 /**
  * @module jsdoc-parse
  * @example
- * var jsdocParse = require('jsdoc-parse')
+ * const jsdocParse = require('jsdoc-parse')
  */
 module.exports = parse
 
 /**
  * @param {object[]} - jsdoc output
  * @param [options] {object}
  * @param [options.private] {boolean} - Include identifier documentation marked as `@private` in the output
+ * @param [options.sort-by] {string|string[]} - Sort by one of more properties, e.g. `[ 'kind', 'category' ]`. Defaults to `[ 'scope', 'category', 'kind', 'order' ]`.
  * @returns {object[]}
  * @alias module:jsdoc-parse
  */
 function parse (jsdocData, options) {
   options = options || {}
   let data = transform(jsdocData)
 
+  /* filter out ignored or private doclets */
   data = data.filter(function (doclet) {
-    var parent = data.find(d => d.id === doclet.memberof) || {}
+    const parent = data.find(d => d.id === doclet.memberof) || {}
     if (doclet.ignore || parent.ignore) {
       return false
     } else if (!options.private && (doclet.access === 'private' || parent.access === 'private')) {
@@ -30,5 +32,17 @@ function parse (jsdocData, options) {
     }
   })
 
+  /* sort */
+  data = sort(data, options['sort-by'])
   return data
 }
+
+function sort (array, properties) {
+  const sortBy = require('sort-array')
+  const customOrder = {
+    kind: [ 'class', 'constructor', 'mixin', 'member', 'namespace', 'enum', 'constant', 'function', 'event', 'typedef', 'external' ],
+    scope: [ 'global', 'instance', 'static', 'inner' ]
+  }
+  properties = properties || [ 'scope', 'category', 'kind', 'order' ]
+  return sortBy(array, properties, customOrder)
+}

package.json

@@ -28,6 +28,7 @@
     "lodash.omit": "^4.4.0",
     "lodash.pick": "^4.3.0",
     "reduce-extract": "^1.0.0",
+    "sort-array": "^1.1.1",
     "test-value": "^2.0.0"
   },
   "devDependencies": {