From 5536e3b690614e24e31e1c8af46aed71749aa85f Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Thu, 6 Oct 2016 20:59:00 +0100 Subject: [PATCH] API docs --- docs/API.md | 28 ++++++++++++++++++++++------ es5/test/async.js | 3 +++ es5/test/sync.js | 4 ---- src/lib/jsdoc-to-markdown.js | 18 ++++++++++++------ src/test/async.js | 1 + src/test/sync.js | 4 ---- 6 files changed, 38 insertions(+), 20 deletions(-) diff --git a/docs/API.md b/docs/API.md index fa1f6c46..332c0ffb 100644 --- a/docs/API.md +++ b/docs/API.md @@ -13,6 +13,7 @@ const jsdoc2md = require('jsdoc-to-markdown') * [.getTemplateData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData) ⇒ Promise * [.getJsdocData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData) ⇒ Promise * [.clear()](#module_jsdoc-to-markdown--JsdocToMarkdown+clear) ⇒ Promise + * [.getNamepaths(options)](#module_jsdoc-to-markdown--JsdocToMarkdown+getNamepaths) ⇒ object * _sync_ * [.renderSync([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+renderSync) ⇒ string * [.getTemplateDataSync([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateDataSync) ⇒ Array.<object> @@ -67,7 +68,7 @@ Pass in filepaths (`**` glob matching supported) of javascript source files: ### jsdoc2md.getTemplateData([options]) ⇒ Promise -Returns template data (jsdoc-parse output). +Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: async @@ -83,7 +84,7 @@ Returns template data (jsdoc-parse output). ### jsdoc2md.getJsdocData([options]) ⇒ Promise -Returns raw jsdoc data. +Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc). **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: async @@ -95,7 +96,7 @@ Returns raw jsdoc data. | [options.cache] | boolean | Set to false to disable memoisation cache. Defaults to true. | | [options.files] | string | Array.<string> | One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied. | | [options.source] | string | A string containing source code to process. Either `files`, `source` or `data` must be supplied. | -| [options.configure] | string | The path to the configuration file. Default: path/to/jsdoc/conf.json. | +| [options.configure] | string | The path to the [jsdoc configuration file](http://usejsdoc.org/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. | | [options.html] | boolean | Enable experimental documentation of `.html` files. | @@ -109,12 +110,27 @@ Clear the cache. **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: async +- + + + +### jsdoc2md.getNamepaths(options) ⇒ object +Returns all [jsdoc namepaths](http://usejsdoc.org/about-namepaths.html) found in the supplied source code. + +**Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) +**Category**: async + +| Param | Type | Description | +| --- | --- | --- | +| options | object | options to pass to [getTemplateData](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData) | + + - ### jsdoc2md.renderSync([options]) ⇒ string -Sync version of `render`. +Sync version of [render](#module_jsdoc-to-markdown--JsdocToMarkdown+render). **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: sync @@ -134,7 +150,7 @@ const docs = jsdoc2md.renderSync('lib/*.js') ### jsdoc2md.getTemplateDataSync([options]) ⇒ Array.<object> -Sync version of `getTemplateData`. +Sync version of [getTemplateData](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData). **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: sync @@ -149,7 +165,7 @@ Sync version of `getTemplateData`. ### jsdoc2md.getJsdocDataSync([options]) ⇒ Array.<object> -Sync version of `getJsdocData`. +Sync version of [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData). **Kind**: instance method of [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown) **Category**: sync diff --git a/es5/test/async.js b/es5/test/async.js index 307db498..013d6a0b 100644 --- a/es5/test/async.js +++ b/es5/test/async.js @@ -10,6 +10,9 @@ try { jsdoc2md._usage.defaults.set('tid', 'UA-70853320-4'); jsdoc2md._usage.queuePath = 'tmp-test/unsent.json'; jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json'; +process.on('beforeExit', function () { + return jsdoc2md._usage.send(); +}); var runner = new TestRunner(); var inputFile = 'src/test/fixture/ignore.js'; diff --git a/es5/test/sync.js b/es5/test/sync.js index cd4aedd4..9c6764b7 100644 --- a/es5/test/sync.js +++ b/es5/test/sync.js @@ -11,10 +11,6 @@ var fs = require('fs'); try { fs.mkdirSync('tmp-test'); } catch (err) {} -jsdoc2md._usage.defaults.set('tid', 'UA-70853320-4'); -jsdoc2md._usage.queuePath = 'tmp-test/unsent.json'; -jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json'; - var runner = new TestRunner(); var inputFile = 'src/test/fixture/ignore.js'; diff --git a/src/lib/jsdoc-to-markdown.js b/src/lib/jsdoc-to-markdown.js index 433cb379..614a622b 100644 --- a/src/lib/jsdoc-to-markdown.js +++ b/src/lib/jsdoc-to-markdown.js @@ -57,7 +57,7 @@ class JsdocToMarkdown { } /** - * Sync version of `render`. + * Sync version of {@link module:jsdoc-to-markdown#render}. * * @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#render}. * @return {string} @@ -77,7 +77,7 @@ class JsdocToMarkdown { } /** - * Returns template data (jsdoc-parse output). + * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). * * @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}. * @return {Promise} @@ -92,7 +92,7 @@ class JsdocToMarkdown { } /** - * Sync version of `getTemplateData`. + * Sync version of {@link module:jsdoc-to-markdown#getTemplateData}. * * @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}. * @return {object[]} @@ -106,13 +106,13 @@ class JsdocToMarkdown { } /** - * Returns raw jsdoc data. + * Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc). * * @param [options] {object} - the options * @param [options.cache] {boolean} - Set to false to disable memoisation cache. Defaults to true. * @param [options.files] {string|string[]} - One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied. * @param [options.source] {string} - A string containing source code to process. Either `files`, `source` or `data` must be supplied. - * @param [options.configure] {string} - The path to the configuration file. Default: path/to/jsdoc/conf.json. + * @param [options.configure] {string} - The path to the [jsdoc configuration file](http://usejsdoc.org/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. * @param [options.html] {boolean} - Enable experimental documentation of `.html` files. * @return {Promise} * @fulfil {object[]} @@ -124,7 +124,7 @@ class JsdocToMarkdown { } /** - * Sync version of `getJsdocData`. + * Sync version of {@link module:jsdoc-to-markdown#getJsdocData}. * * @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}. * @return {object[]} @@ -144,6 +144,12 @@ class JsdocToMarkdown { return jsdocApi.cache.clear().then(() => dmd.cache.clear()) } + /** + * Returns all [jsdoc namepaths](http://usejsdoc.org/about-namepaths.html) found in the supplied source code. + * @param {object} - options to pass to {@link module:jsdoc-to-markdown#getTemplateData} + * @returns {object} + * @category async + */ getNamepaths (options) { return this.getTemplateData(options) .then(data => { diff --git a/src/test/async.js b/src/test/async.js index a80ef02a..e0bc53a7 100644 --- a/src/test/async.js +++ b/src/test/async.js @@ -11,6 +11,7 @@ try { jsdoc2md._usage.defaults.set('tid', 'UA-70853320-4') jsdoc2md._usage.queuePath = 'tmp-test/unsent.json' jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json' +process.on('beforeExit', () => jsdoc2md._usage.send()) const runner = new TestRunner() const inputFile = 'src/test/fixture/ignore.js' diff --git a/src/test/sync.js b/src/test/sync.js index 0361e85d..ff47a9f7 100644 --- a/src/test/sync.js +++ b/src/test/sync.js @@ -13,10 +13,6 @@ try { } catch (err) { // exists } -jsdoc2md._usage.defaults.set('tid', 'UA-70853320-4') -jsdoc2md._usage.queuePath = 'tmp-test/unsent.json' -jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json' - const runner = new TestRunner() const inputFile = 'src/test/fixture/ignore.js'