jsdoc-to-markdown - npm Package Compare versions

Comparing version 2.0.0-alpha.7 to 2.0.0-alpha.8

es5/bin/cli.js

 'use strict';
 
 var tool = require('command-line-tool');
-var UsageStats = require('usage-stats');
 var path = require('path');
 var version = require('../../package').version;
-var usageStats = new UsageStats({
-  appName: 'jsdoc2md',
-  version: version,
-  tid: 'UA-70853320-3'
-});
 
@@ -17,6 +11,2 @@ var cli = parseCommandLine();
 
-if (options['no-usage-stats']) usageStats.disable();
-
-usageStats.start();
-
 if (options.help) {
@@ -27,3 +17,2 @@ tool.printOutput(cli.usage);
 } else if (options.clear) {
-  usageStats.screenView('clear').end().send();
   var jsdoc2md = require('../../');
@@ -34,9 +23,3 @@ jsdoc2md.clear().catch(tool.halt);
 
-  Object.keys(options).forEach(function (option) {
-    var dontSend = ['files', 'source'];
-    usageStats.event('option', option, dontSend.includes(option) ? undefined : options[option]);
-  });
-
   if (options.config) {
-    usageStats.screenView('config').end().send();
     var omit = require('lodash.omit');
@@ -56,3 +39,2 @@ tool.stop(JSON.stringify(omit(options, 'config'), null, '  '));
   if (options.json) {
-    usageStats.screenView('json').end().send();
     _jsdoc2md.getTemplateData(options).then(function (json) {
@@ -62,3 +44,2 @@ tool.printOutput(JSON.stringify(json, null, '  '));
   } else if (options.jsdoc) {
-    usageStats.screenView('jsdoc').end().send();
     _jsdoc2md.getJsdocData(options).then(function (json) {
@@ -68,3 +49,2 @@ tool.printOutput(JSON.stringify(json, null, '  '));
   } else if (options.stats) {
-    usageStats.screenView('stats').end().send();
     _jsdoc2md.getStats(options.files).then(function (json) {
@@ -74,3 +54,2 @@ tool.printOutput(JSON.stringify(json, null, '  '));
   } else {
-    usageStats.screenView('gen').end().send();
     var fs = require('fs');
@@ -77,0 +56,0 @@ if (options.template) options.template = fs.readFileSync(options.template, 'utf8');

es5/lib/jsdoc-to-markdown.js

@@ -5,10 +5,34 @@ 'use strict';
 
-exports.render = render;
-exports.renderSync = renderSync;
-exports.getTemplateData = getTemplateData;
-exports.getTemplateDataSync = getTemplateDataSync;
-exports.getJsdocData = getJsdocData;
-exports.getJsdocDataSync = getJsdocDataSync;
-exports.clear = clear;
+var version = require('../../package').version;
+var UsageStats = require('usage-stats');
+var usageStats = new UsageStats({
+  appName: 'jsdoc2md',
+  version: version,
+  tid: 'UA-70853320-3'
+});
 
+exports.render = function (options) {
+  return stats('render', options, render);
+};
+exports.renderSync = function (options) {
+  return stats('renderSync', options, renderSync, true);
+};
+exports.getTemplateData = function (options) {
+  return stats('getTemplateData', options, getTemplateData);
+};
+exports.getTemplateDataSync = function (options) {
+  return stats('getTemplateDataSync', options, getTemplateDataSync, true);
+};
+exports.getJsdocData = function (options) {
+  return stats('getJsdocData', options, getJsdocData);
+};
+exports.getJsdocDataSync = function (options) {
+  return stats('getJsdocDataSync', options, getJsdocDataSync, true);
+};
+exports.clear = function () {
+  return stats('clear', null, clear);
+};
+
+exports._usageStats = usageStats;
+
 function render(options) {
@@ -18,3 +42,3 @@ options = options || {};
   var dmdOptions = new DmdOptions(options);
-  return this.getTemplateData(options).then(function (templateData) {
+  return getTemplateData(options).then(function (templateData) {
     return dmd(templateData, dmdOptions);
@@ -28,3 +52,3 @@ });
   var dmdOptions = new DmdOptions(options);
-  return dmd(this.getTemplateDataSync(options), dmdOptions);
+  return dmd(getTemplateDataSync(options), dmdOptions);
 }
@@ -115,2 +139,37 @@
   this['member-index-format'] = options['member-index-format'] || 'grouped';
-};
+};
+
+function stats(screenName, options, command, sync) {
+  if (options['no-usage-stats']) {
+    usageStats.disable();
+    return command(options);
+  } else {
+    usageStats.start();
+    usageStats.screenView(screenName);
+    if (options) {
+      Object.keys(options).forEach(function (option) {
+        var dontSend = ['files', 'source'];
+        usageStats.event('option', option, dontSend.includes(option) ? undefined : options[option]);
+      });
+    }
+    if (sync) {
+      try {
+        var output = command(options);
+        usageStats.end().send();
+        return output;
+      } catch (err) {
+        usageStats.exception(err.message, 1);
+        throw err;
+      }
+    } else {
+      return command(options).then(function (output) {
+        usageStats.end().send();
+        return output;
+      }).catch(function (err) {
+        usageStats.exception(err.message, true);
+        usageStats.end().send();
+        throw err;
+      });
+    }
+  }
+}

es5/test/async.js

@@ -6,2 +6,3 @@ 'use strict';
 var a = require('assert');
+jsdoc2md._usageStats.disable();
 
@@ -8,0 +9,0 @@ var inputFile = 'src/test/fixture/ignore.js';

es5/test/sync.js

@@ -6,2 +6,3 @@ 'use strict';
 var a = require('assert');
+jsdoc2md._usageStats.disable();
 
@@ -8,0 +9,0 @@ var inputFile = 'src/test/fixture/ignore.js';

package.json

 {
   "name": "jsdoc-to-markdown",
   "author": "Lloyd Brookes",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.8",
   "description": "jsdoc-annotated source in, markdown API docs out.",
@@ -34,5 +34,5 @@ "repository": "https://github.com/jsdoc2md/jsdoc-to-markdown",
     "feature-detect-es6": "^1.3.1",
-    "jsdoc-api": "^1.2.3",
+    "jsdoc-api": "^1.2.4",
     "jsdoc-parse": "^2.0.5-0",
-    "usage-stats": "~0.1.3",
+    "usage-stats": "~0.1.4",
     "walk-back": "^2.0.1"
@@ -39,0 +39,0 @@ },

README.md

@@ -9,10 +9,40 @@ [![view on npm](http://img.shields.io/npm/v/jsdoc-to-markdown.svg)](https://www.npmjs.org/package/jsdoc-to-markdown)
 
-***This is the next version of the tool, a work in progress.***
-
 # jsdoc-to-markdown
 Generates markdown documentation from [jsdoc](http://usejsdoc.org) annotated source code. Useful for injecting API docs into project README files.
 
-* [API documentation](https://github.com/jsdoc2md/jsdoc-to-markdown/blob/next/docs/API.md)
-* [Example output](https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/Exemplary-APIs)
+## Synopsis
 
+1\. Document your code using valid jsdoc comments.
+
+```js
+/**
+ * A quite wonderful function.
+ * @param {object} - privacy gown
+ * @param {object} - security
+ * @returns {survival}
+ */
+function protection (cloak, dagger) {}
+```
+
+2\. Run a command.
+
+```sh
+$ jsdoc2md example.js
+```
+
+3\. Get markdown output.
+
+```markdown
+## protection(cloak, dagger) ⇒ <code>survival</code>
+A quite wonderful function.
+
+**Kind**: global function  
+
+| Param  | Type                | Description  |
+| ------ | ------------------- | ------------ |
+| cloak  | <code>object</code> | privacy gown |
+| dagger | <code>object</code> | security     |
+
+```
+
 ## Install
@@ -24,5 +54,9 @@
 
+## See also
 
+* [API documentation](https://github.com/jsdoc2md/jsdoc-to-markdown/blob/next/docs/API.md)
+* The [wiki](https://github.com/jsdoc2md/jsdoc-to-markdown/wiki) for example output, FAQs, tutorials, plugins, use with gulp/grunt etc.
+
 * * *
 
 &copy; 2014-16 Lloyd Brookes <[e-mail]>.

src/bin/cli.js

 'use strict'
 const tool = require('command-line-tool')
-const UsageStats = require('usage-stats')
 const path = require('path')
 const version = require('../../package').version
-const usageStats = new UsageStats({
-  appName: 'jsdoc2md',
-  version: version,
-  tid: 'UA-70853320-3'
-})
 
@@ -16,7 +10,2 @@ const cli = parseCommandLine()
 
-/* when disabled, all usageStats methods are no-ops */
-if (options['no-usage-stats']) usageStats.disable()
-
-usageStats.start()
-
 /* jsdoc2md --help */
@@ -32,3 +21,2 @@ if (options.help) {
 } else if (options.clear) {
-  usageStats.screenView('clear').end().send()
   const jsdoc2md = require('../../')
@@ -40,10 +28,4 @@ jsdoc2md.clear().catch(tool.halt)
 
-  Object.keys(options).forEach(option => {
-    const dontSend = [ 'files', 'source' ]
-    usageStats.event('option', option, dontSend.includes(option) ? undefined : options[option])
-  })
-
   /* jsdoc2md --config */
   if (options.config) {
-    usageStats.screenView('config').end().send()
     const omit = require('lodash.omit')
@@ -66,3 +48,2 @@ tool.stop(JSON.stringify(omit(options, 'config'), null, '  '))
   if (options.json) {
-    usageStats.screenView('json').end().send()
     jsdoc2md.getTemplateData(options)
@@ -76,3 +57,2 @@ .then(function (json) {
   } else if (options.jsdoc) {
-    usageStats.screenView('jsdoc').end().send()
     jsdoc2md
@@ -87,3 +67,2 @@ .getJsdocData(options)
   } else if (options.stats) {
-    usageStats.screenView('stats').end().send()
     jsdoc2md
@@ -98,3 +77,2 @@ .getStats(options.files)
   } else {
-    usageStats.screenView('gen').end().send()
     const fs = require('fs')
@@ -101,0 +79,0 @@ if (options.template) options.template = fs.readFileSync(options.template, 'utf8')

src/lib/jsdoc-to-markdown.js

 'use strict'
+const version = require('../../package').version
+const UsageStats = require('usage-stats')
+const usageStats = new UsageStats({
+  appName: 'jsdoc2md',
+  version: version,
+  tid: 'UA-70853320-3'
+})
 
@@ -9,10 +16,27 @@ /**
  */
-exports.render = render
-exports.renderSync = renderSync
-exports.getTemplateData = getTemplateData
-exports.getTemplateDataSync = getTemplateDataSync
-exports.getJsdocData = getJsdocData
-exports.getJsdocDataSync = getJsdocDataSync
-exports.clear = clear
+exports.render = function (options) {
+  return stats('render', options, render)
+}
+exports.renderSync = function (options) {
+  return stats('renderSync', options, renderSync, true)
+}
+exports.getTemplateData = function (options) {
+  return stats('getTemplateData', options, getTemplateData)
+}
+exports.getTemplateDataSync = function (options) {
+  return stats('getTemplateDataSync', options, getTemplateDataSync, true)
+}
+exports.getJsdocData = function (options) {
+  return stats('getJsdocData', options, getJsdocData)
+}
+exports.getJsdocDataSync = function (options) {
+  return stats('getJsdocDataSync', options, getJsdocDataSync, true)
+}
+exports.clear = function () {
+  return stats('clear', null, clear)
+}
 
+/* exposed so the test suite can disable it */
+exports._usageStats = usageStats
+
 /**
@@ -36,3 +60,3 @@ * Returns markdown documentation from jsdoc-annoted source code.
   const dmdOptions = new DmdOptions(options)
-  return this.getTemplateData(options)
+  return getTemplateData(options)
     .then(templateData => dmd(templateData, dmdOptions))
@@ -56,3 +80,3 @@ }
   const dmdOptions = new DmdOptions(options)
-  return dmd(this.getTemplateDataSync(options), dmdOptions)
+  return dmd(getTemplateDataSync(options), dmdOptions)
 }
@@ -269,1 +293,39 @@
 }
+
+function stats (screenName, options, command, sync) {
+  /* when disabled, all usageStats methods are no-ops */
+  if (options['no-usage-stats']) {
+    usageStats.disable()
+    return command(options)
+  } else {
+    usageStats.start()
+    usageStats.screenView(screenName)
+    if (options) {
+      Object.keys(options).forEach(option => {
+        const dontSend = [ 'files', 'source' ]
+        usageStats.event('option', option, dontSend.includes(option) ? undefined : options[option])
+      })
+    }
+    if (sync) {
+      try {
+        const output = command(options)
+        usageStats.end().send()
+        return output
+      } catch (err) {
+        usageStats.exception(err.message, 1)
+        throw err
+      }
+    } else {
+      return command(options)
+        .then(output => {
+          usageStats.end().send()
+          return output
+        })
+        .catch(err => {
+          usageStats.exception(err.message, true)
+          usageStats.end().send()
+          throw err
+        })
+    }
+  }
+}

src/test/async.js

@@ -5,2 +5,3 @@ 'use strict'
 const a = require('assert')
+jsdoc2md._usageStats.disable()
 
@@ -7,0 +8,0 @@ const inputFile = 'src/test/fixture/ignore.js'

src/test/sync.js

@@ -5,2 +5,3 @@ 'use strict'
 const a = require('assert')
+jsdoc2md._usageStats.disable()
 
@@ -7,0 +8,0 @@ const inputFile = 'src/test/fixture/ignore.js'

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

58826

increased by4.67%

Lines of code

1082

increased by7.98%

Number of lines in readme file

60

increased by130.77%

Worsened metrics

Number of package files

26

decreased by-7.14%

Dependency changes

• Updatedjsdoc-api@^1.2.4

• Updatedusage-stats@~0.1.4