Socket
Socket
Sign inDemoInstall

jsdoc-to-markdown

Package Overview
Dependencies
84
Maintainers
1
Versions
119
Alerts
File Explorer

Advanced tools

npm Scripts

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 2.0.0-alpha.22 to 2.0.0-alpha.23

293

docs/API.md

@@ -16,2 +16,3 @@ <a name="module_jsdoc-to-markdown"></a>

* [.clear()](#module_jsdoc-to-markdown--JsdocToMarkdown+clear) ⇒ <code>Promise</code>
* [.getNamepaths(options)](#module_jsdoc-to-markdown--JsdocToMarkdown+getNamepaths) ⇒ <code>object</code>
* _sync_

@@ -43,3 +44,18 @@ * [.renderSync([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+renderSync) ⇒ <code>string</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> &#124; <code>[DmdOptions](#DmdOptions)</code> | the options |
| [options] | <code>object</code> | Accepts all [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData) options plus the following: |
| [options.data] | <code>Array.&lt;object&gt;</code> | Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData`. Either `files`, `source` or `data` must be supplied. |
| [options.template] | <code>string</code> | The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output. |
| [options.heading-depth] | <code>number</code> | The initial heading depth. For example, with a value of `2` the top-level markdown headings look like `"## The heading"`. |
| [options.example-lang] | <code>string</code> | Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: `--example-lang js`. Use the special value `none` for no specific language. While using this option, you can override the supplied language for any @example by specifying the `@lang` subtag, e.g `@example @lang hbs`. Specifying `@example @lang off` will disable code blocks for that example. |
| [options.plugin] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | Use an installed package containing helper and/or partial overrides. |
| [options.helper] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | handlebars helper files to override or extend the default set. |
| [options.partial] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | handlebars partial files to override or extend the default set. |
| [options.name-format] | <code>string</code> | Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or `<code></code>`). |
| [options.no-gfm] | <code>boolean</code> | By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax. |
| [options.separators] | <code>boolean</code> | Put `<hr>` breaks between identifiers. Improves readability on bulky docs. |
| [options.module-index-format] | <code>string</code> | none, grouped, table, dl. |
| [options.global-index-format] | | none, grouped, table, dl. |
| [options.param-list-format] | | Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed. |
| [options.property-list-format] | | list, table. |
| [options.member-index-format] | | grouped, list |

@@ -57,3 +73,3 @@ **Example**

### jsdoc2md.getTemplateData([options]) ⇒ <code>Promise</code>
Returns template data (jsdoc-parse output).
Returns the template data (jsdoc-parse output) which is fed into the output template (dmd).

@@ -66,3 +82,3 @@ **Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> | the options |
| [options] | <code>object</code> | Identical options to [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData). |

@@ -75,3 +91,3 @@

### jsdoc2md.getJsdocData([options]) ⇒ <code>Promise</code>
Returns raw jsdoc data.
Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc).

@@ -84,3 +100,8 @@ **Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> | the options |
| [options] | <code>object</code> | the options |
| [options.no-cache] | <code>boolean</code> | By default results are cached to speed up repeat invocations. Set to true to disable this. |
| [options.files] | <code>string</code> &#124; <code>Array.&lt;string&gt;</code> | One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied. |
| [options.source] | <code>string</code> | A string containing source code to process. Either `files`, `source` or `data` must be supplied. |
| [options.configure] | <code>string</code> | The path to the [jsdoc configuration file](http://usejsdoc.org/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. |
| [options.html] | <code>boolean</code> | Enable experimental documentation of `.html` files. |

@@ -100,6 +121,21 @@

<a name="module_jsdoc-to-markdown--JsdocToMarkdown+getNamepaths"></a>
### jsdoc2md.getNamepaths(options) ⇒ <code>object</code>
Returns all [jsdoc namepaths](http://usejsdoc.org/about-namepaths.html) found in the supplied source code.
**Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>
**Category**: async
| Param | Type | Description |
| --- | --- | --- |
| options | <code>object</code> | options to pass to [getTemplateData](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData) |
-
<a name="module_jsdoc-to-markdown--JsdocToMarkdown+renderSync"></a>
### jsdoc2md.renderSync([options]) ⇒ <code>string</code>
Returns markdown documentation from jsdoc-annoted source code.
Sync version of [render](#module_jsdoc-to-markdown--JsdocToMarkdown+render).

@@ -112,3 +148,3 @@ **Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> &#124; <code>[DmdOptions](#DmdOptions)</code> | the options |
| [options] | <code>object</code> | Identical options to [render](#module_jsdoc-to-markdown--JsdocToMarkdown+render). |

@@ -125,3 +161,3 @@ **Example**

### jsdoc2md.getTemplateDataSync([options]) ⇒ <code>Array.&lt;object&gt;</code>
Returns template data (jsdoc-parse output).
Sync version of [getTemplateData](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData).

@@ -133,3 +169,3 @@ **Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> | the options |
| [options] | <code>object</code> | Identical options to [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData). |

@@ -142,3 +178,3 @@

### jsdoc2md.getJsdocDataSync([options]) ⇒ <code>Array.&lt;object&gt;</code>
Returns raw jsdoc data.
Sync version of [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData).

@@ -150,3 +186,3 @@ **Kind**: instance method of <code>[JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)</code>

| --- | --- | --- |
| [options] | <code>[JsdocOptions](#JsdocOptions)</code> | the options |
| [options] | <code>object</code> | Identical options to [getJsdocData](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData). |

@@ -157,236 +193,1 @@

<a name="JsdocOptions"></a>
# JsdocOptions
**Kind**: global class
* [JsdocOptions](#JsdocOptions)
* [.cache](#JsdocOptions+cache)
* [.files](#JsdocOptions+files) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
* [.source](#JsdocOptions+source) : <code>string</code>
* [.data](#JsdocOptions+data) : <code>Array.&lt;object&gt;</code>
* [.configure](#JsdocOptions+configure) : <code>string</code>
* [.html](#JsdocOptions+html) : <code>boolean</code>
-
<a name="JsdocOptions+cache"></a>
## options.cache
Set to false to disable memoisation cache. Defaults to true.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="JsdocOptions+files"></a>
## options.files : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="JsdocOptions+source"></a>
## options.source : <code>string</code>
A string containing source code to process. Either `files`, `source` or `data` must be supplied.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="JsdocOptions+data"></a>
## options.data : <code>Array.&lt;object&gt;</code>
Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData`. Either `files`, `source` or `data` must be supplied.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="JsdocOptions+configure"></a>
## options.configure : <code>string</code>
The path to the configuration file. Default: path/to/jsdoc/conf.json.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="JsdocOptions+html"></a>
## options.html : <code>boolean</code>
Enable experimental parsing of `.html` files.
**Kind**: instance property of <code>[JsdocOptions](#JsdocOptions)</code>
-
<a name="DmdOptions"></a>
# DmdOptions
**Kind**: global class
* [DmdOptions](#DmdOptions)
* [.template](#DmdOptions+template) : <code>string</code>
* [.heading-depth](#DmdOptions+heading-depth) : <code>number</code>
* [.example-lang](#DmdOptions+example-lang) : <code>string</code>
* [.plugin](#DmdOptions+plugin) : <code>array</code>
* [.helper](#DmdOptions+helper) : <code>array</code>
* [.partial](#DmdOptions+partial) : <code>array</code>
* [.name-format](#DmdOptions+name-format) : <code>string</code>
* [.no-gfm](#DmdOptions+no-gfm) : <code>boolean</code>
* [.separators](#DmdOptions+separators) : <code>boolean</code>
* [.module-index-format](#DmdOptions+module-index-format) : <code>string</code>
* [.global-index-format](#DmdOptions+global-index-format) : <code>string</code>
* [.param-list-format](#DmdOptions+param-list-format) : <code>string</code>
* [.property-list-format](#DmdOptions+property-list-format) : <code>string</code>
* [.member-index-format](#DmdOptions+member-index-format) : <code>string</code>
* [.private](#DmdOptions+private) : <code>boolean</code>
-
<a name="DmdOptions+template"></a>
## options.template : <code>string</code>
The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+heading-depth"></a>
## options.heading-depth : <code>number</code>
The initial heading depth. For example, with a value of `2` the top-level markdown headings look like `"## The heading"`.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+example-lang"></a>
## options.example-lang : <code>string</code>
Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: `--example-lang js`. Use the special value `none` for no specific language. While using this option, you can override the supplied language for any @example by specifying the `@lang` subtag, e.g `@example @lang hbs`. Specifying `@example @lang off` will disable code blocks for that example.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+plugin"></a>
## options.plugin : <code>array</code>
Use an installed package containing helper and/or partial overrides
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+helper"></a>
## options.helper : <code>array</code>
handlebars helper files to override or extend the default set
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+partial"></a>
## options.partial : <code>array</code>
handlebars partial files to override or extend the default set
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+name-format"></a>
## options.name-format : <code>string</code>
Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or `<code></code>`)
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+no-gfm"></a>
## options.no-gfm : <code>boolean</code>
By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+separators"></a>
## options.separators : <code>boolean</code>
Put `<hr>` breaks between identifiers. Improves readability on bulky docs.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
**Default**: <code>false</code>
-
<a name="DmdOptions+module-index-format"></a>
## options.module-index-format : <code>string</code>
none, grouped, table, dl
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+global-index-format"></a>
## options.global-index-format : <code>string</code>
none, grouped, table, dl
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+param-list-format"></a>
## options.param-list-format : <code>string</code>
Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+property-list-format"></a>
## options.property-list-format : <code>string</code>
list, table
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+member-index-format"></a>
## options.member-index-format : <code>string</code>
grouped, list
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
-
<a name="DmdOptions+private"></a>
## options.private : <code>boolean</code>
Show identifiers marked `@private` in the output.
**Kind**: instance property of <code>[DmdOptions](#DmdOptions)</code>
**Default**: <code>false</code>
-

8

es5/bin/cli.js

@@ -10,7 +10,2 @@ 'use strict';

if (options['no-cache']) {
options.cache = false;
delete options['no-cache'];
}
if (options.help) {

@@ -59,3 +54,4 @@ tool.printOutput(cli.usage);

_jsdoc2md.render(options).then(function (output) {
return process.stdout.write(output);
process.stdout.write(output);
process.exit(0);
}).catch(handleError);

@@ -62,0 +58,0 @@ }

34

es5/lib/dmd-options.js

@@ -8,35 +8,7 @@ 'use strict';

var arrayify = require('array-back');
this.template = options.template || '{{>main}}';
this['heading-depth'] = options['heading-depth'] || 2;
this['example-lang'] = options['example-lang'] || 'js';
this.plugin = arrayify(options.plugin);
this.helper = arrayify(options.helper);
this.partial = arrayify(options.partial);
this['name-format'] = options['name-format'];
this['no-gfm'] = options['no-gfm'];
this.separators = options.separators;
this['module-index-format'] = options['module-index-format'] || 'dl';
this['global-index-format'] = options['global-index-format'] || 'dl';
this['param-list-format'] = options['param-list-format'] || 'table';
this['property-list-format'] = options['property-list-format'] || 'table';
this['member-index-format'] = options['member-index-format'] || 'grouped';
this.private = options.private;
Object.assign(this, options);
this.noCache = options['no-cache'];
delete this['no-cache'];
};
module.exports = DmdOptions;

16

es5/lib/jsdoc-options.js

@@ -8,17 +8,7 @@ 'use strict';

options = options || {};
this.cache = options.cache === undefined ? true : options.cache;
this.files = options.files;
this.source = options.source;
this.data = options.data;
this.configure = options.configure;
this.html = options.html;
Object.assign(this, options);
this.cache = !options['no-cache'];
delete this['no-cache'];
};
module.exports = JsdocOptions;

1

es5/lib/jsdoc-to-markdown.js

@@ -10,3 +10,2 @@ 'use strict';

var dmd = require('dmd');
var os = require('os');
var DmdOptions = require('./dmd-options');

@@ -13,0 +12,0 @@ var JsdocOptions = require('./jsdoc-options');

120

es5/test/async.js

@@ -13,2 +13,5 @@ 'use strict';

jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json';
process.on('beforeExit', function () {
return jsdoc2md._usage.send();
});

@@ -19,3 +22,3 @@ var runner = new TestRunner();

runner.test('.render({ files })', function () {
return jsdoc2md.render({ files: inputFile, cache: false }).then(function (result) {
return jsdoc2md.render({ files: inputFile }).then(function (result) {
return a.ok(/a visible global/.test(result));

@@ -27,28 +30,28 @@ });

var data = [{
"id": "visible",
"longname": "visible",
"name": "visible",
"kind": "member",
"scope": "global",
"description": "a visible global",
"meta": {
"lineno": 4,
"filename": "ignore.js"
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
"order": 0
order: 0
}, {
"id": "invisible",
"longname": "invisible",
"name": "invisible",
"kind": "member",
"scope": "global",
"description": "an ignored global",
"ignore": true,
"meta": {
"lineno": 10,
"filename": "ignore.js"
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
"order": 1
order: 1
}];
return jsdoc2md.render({ data: data, cache: false }).then(function (result) {
return jsdoc2md.render({ data: data }).then(function (result) {
return a.ok(/a visible global/.test(result));

@@ -59,3 +62,3 @@ });

runner.test('.render({ files, heading-depth: 4 })', function () {
return jsdoc2md.render({ files: inputFile, cache: false, 'heading-depth': 4 }).then(function (result) {
return jsdoc2md.render({ files: inputFile, 'heading-depth': 4 }).then(function (result) {
return a.ok(/#### visible/.test(result));

@@ -67,3 +70,3 @@ });

var inputFile = 'src/test/fixture/params.js';
return jsdoc2md.render({ files: inputFile, cache: false, 'param-list-format': 'list' }).then(function (result) {
return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list' }).then(function (result) {
return a.ok(/- one/.test(result));

@@ -74,3 +77,3 @@ });

runner.test('.getTemplateData({ files })', function () {
return jsdoc2md.getTemplateData({ files: inputFile, cache: false }).then(function (result) {
return jsdoc2md.getTemplateData({ files: inputFile }).then(function (result) {
return a.ok(result[0].id);

@@ -81,5 +84,68 @@ });

runner.test('.getJsdocData({ files })', function () {
return jsdoc2md.getJsdocData({ files: inputFile, cache: false }).then(function (result) {
return jsdoc2md.getJsdocData({ files: inputFile }).then(function (result) {
return a.ok(result[0].longname);
});
});
runner.test('.render({ files, noCache })', function () {
return jsdoc2md.render({ files: inputFile, noCache: true }).then(function (result) {
return a.ok(/a visible global/.test(result));
});
});
runner.test('.render({ data, noCache })', function () {
var data = [{
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
order: 0
}, {
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
order: 1
}];
return jsdoc2md.render({ data: data, noCache: true }).then(function (result) {
return a.ok(/a visible global/.test(result));
});
});
runner.test('.render({ files, heading-depth: 4, noCache })', function () {
return jsdoc2md.render({ files: inputFile, 'heading-depth': 4, noCache: true }).then(function (result) {
return a.ok(/#### visible/.test(result));
});
});
runner.test('.render({ files, param-list-format: list, noCache })', function () {
var inputFile = 'src/test/fixture/params.js';
return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list', noCache: true }).then(function (result) {
return a.ok(/- one/.test(result));
});
});
runner.test('.getTemplateData({ files, noCache })', function () {
return jsdoc2md.getTemplateData({ files: inputFile, noCache: true }).then(function (result) {
return a.ok(result[0].id);
});
});
runner.test('.getJsdocData({ files, noCache })', function () {
return jsdoc2md.getJsdocData({ files: inputFile, noCache: true }).then(function (result) {
return a.ok(result[0].longname);
});
});

47

es5/test/sync.js

@@ -8,3 +8,2 @@ 'use strict';

var a = require('assert');
var path = require('path');
var fs = require('fs');

@@ -15,6 +14,2 @@

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

@@ -30,26 +25,26 @@ var inputFile = 'src/test/fixture/ignore.js';

var data = [{
"id": "visible",
"longname": "visible",
"name": "visible",
"kind": "member",
"scope": "global",
"description": "a visible global",
"meta": {
"lineno": 4,
"filename": "ignore.js"
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
"order": 0
order: 0
}, {
"id": "invisible",
"longname": "invisible",
"name": "invisible",
"kind": "member",
"scope": "global",
"description": "an ignored global",
"ignore": true,
"meta": {
"lineno": 10,
"filename": "ignore.js"
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
"order": 1
order: 1
}];

@@ -56,0 +51,0 @@ var result = jsdoc2md.renderSync({ data: data, cache: false });

12

package.json
{
"name": "jsdoc-to-markdown",
"author": "Lloyd Brookes",
"version": "2.0.0-alpha.22",
"version": "2.0.0-alpha.23",
"description": "Generates markdown API documentation from jsdoc annotated source code",

@@ -29,10 +29,10 @@ "repository": "https://github.com/jsdoc2md/jsdoc-to-markdown",

"array-back": "^1.0.3",
"command-line-tool": "^0.6.3",
"command-line-tool": "^0.6.4",
"config-master": "^2.0.4",
"core-js": "^2.4.1",
"dmd": "^2.0.3-4",
"dmd": "^2.1.1",
"feature-detect-es6": "^1.3.1",
"jsdoc-api": "^2.0.3",
"jsdoc-parse": "^2.0.5-0",
"jsdoc2md-stats": "^0.1.0",
"jsdoc-api": "^2.0.5",
"jsdoc-parse": "^2.0.5",
"jsdoc2md-stats": "^1.0.2",
"walk-back": "^2.0.1"

@@ -39,0 +39,0 @@ },

2

README.md

@@ -55,3 +55,3 @@ [![view on npm](http://img.shields.io/npm/v/jsdoc-to-markdown.svg)](https://www.npmjs.org/package/jsdoc-to-markdown)

* [API documentation](https://github.com/jsdoc2md/jsdoc-to-markdown/blob/next/docs/API.md)
* [API documentation](https://github.com/jsdoc2md/jsdoc-to-markdown/blob/master/docs/API.md)
* The [wiki](https://github.com/jsdoc2md/jsdoc-to-markdown/wiki) for example output, FAQs, tutorials, plugins, use with gulp/grunt etc.

@@ -58,0 +58,0 @@

11

src/bin/cli.js

@@ -9,8 +9,2 @@ 'use strict'

/* jsdoc2md --no-cache */
if (options['no-cache']) {
options.cache = false
delete options['no-cache']
}
/* jsdoc2md --help */

@@ -83,3 +77,6 @@ if (options.help) {

.render(options)
.then(output => process.stdout.write(output))
.then(output => {
process.stdout.write(output)
process.exit(0)
})
.catch(handleError)

@@ -86,0 +83,0 @@ }

104

src/lib/dmd-options.js

@@ -8,103 +8,5 @@ 'use strict'

constructor (options) {
const arrayify = require('array-back')
/**
* The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.
* @type {string}
* @default
*/
this.template = options.template || '{{>main}}'
/**
* The initial heading depth. For example, with a value of `2` the top-level markdown headings look like `"## The heading"`.
* @type number
* @default
*/
this['heading-depth'] = options['heading-depth'] || 2
/**
* Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: `--example-lang js`. Use the special value `none` for no specific language. While using this option, you can override the supplied language for any @example by specifying the `@lang` subtag, e.g `@example @lang hbs`. Specifying `@example @lang off` will disable code blocks for that example.
* @type {string}
* @default
*/
this['example-lang'] = options['example-lang'] || 'js'
/**
* Use an installed package containing helper and/or partial overrides
* @type {array}
*/
this.plugin = arrayify(options.plugin)
/**
* handlebars helper files to override or extend the default set
* @type {array}
*/
this.helper = arrayify(options.helper)
/**
* handlebars partial files to override or extend the default set
* @type {array}
*/
this.partial = arrayify(options.partial)
/**
* Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or `<code></code>`)
* @type {string}
*/
this['name-format'] = options['name-format']
/**
* By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
* @type {boolean}
*/
this['no-gfm'] = options['no-gfm']
/**
* Put `<hr>` breaks between identifiers. Improves readability on bulky docs.
* @type {boolean}
* @default false
*/
this.separators = options.separators
/**
* none, grouped, table, dl
* @type {string}
* @default
*/
this['module-index-format'] = options['module-index-format'] || 'dl'
/**
* none, grouped, table, dl
* @type {string}
* @default
*/
this['global-index-format'] = options['global-index-format'] || 'dl'
/**
* Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.
* @type {string}
* @default
*/
this['param-list-format'] = options['param-list-format'] || 'table'
/**
* list, table
* @type {string}
* @default
*/
this['property-list-format'] = options['property-list-format'] || 'table'
/**
* grouped, list
* @type {string}
* @default
*/
this['member-index-format'] = options['member-index-format'] || 'grouped'
/**
* Show identifiers marked `@private` in the output.
* @type {boolean}
* @default false
*/
this.private = options.private
Object.assign(this, options)
this.noCache = options['no-cache']
delete this['no-cache']
}

@@ -111,0 +13,0 @@ }

42

src/lib/jsdoc-options.js
'use strict'
/**
* @typicalname options
*/
class JsdocOptions {
constructor (options) {
options = options || {}
/**
* Set to false to disable memoisation cache. Defaults to true.
*/
this.cache = options.cache === undefined ? true : options.cache
/**
* One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied.
* @type {string|string[]}
*/
this.files = options.files
/**
* A string containing source code to process. Either `files`, `source` or `data` must be supplied.
* @type {string}
*/
this.source = options.source
/**
* Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData`. Either `files`, `source` or `data` must be supplied.
* @type {object[]}
*/
this.data = options.data
/**
* The path to the configuration file. Default: path/to/jsdoc/conf.json.
* @type {string}
*/
this.configure = options.configure
/**
* Enable experimental parsing of `.html` files.
* @type {boolean}
*/
this.html = options.html
Object.assign(this, options)
this.cache = !options['no-cache']
delete this['no-cache']
}

@@ -45,0 +9,0 @@ }

49

src/lib/jsdoc-to-markdown.js

@@ -5,3 +5,2 @@ 'use strict'

const dmd = require('dmd')
const os = require('os')
const DmdOptions = require('./dmd-options')

@@ -24,3 +23,18 @@ const JsdocOptions = require('./jsdoc-options')

*
* @param [options] {JsdocOptions | DmdOptions} - the options
* @param [options] {object} - Accepts all {@link module:jsdoc-to-markdown#getJsdocData} options plus the following:
* @param [options.data] {object[]} - Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData`. Either `files`, `source` or `data` must be supplied.
* @param [options.template] {string} - The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.
* @param [options.heading-depth] {number} - The initial heading depth. For example, with a value of `2` the top-level markdown headings look like `"## The heading"`.
* @param [options.example-lang] {string} - Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: `--example-lang js`. Use the special value `none` for no specific language. While using this option, you can override the supplied language for any @example by specifying the `@lang` subtag, e.g `@example @lang hbs`. Specifying `@example @lang off` will disable code blocks for that example.
* @param [options.plugin] {string|string[]} - Use an installed package containing helper and/or partial overrides.
* @param [options.helper] {string|string[]} - handlebars helper files to override or extend the default set.
* @param [options.partial] {string|string[]} - handlebars partial files to override or extend the default set.
* @param [options.name-format] {string} - Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or `<code></code>`).
* @param [options.no-gfm] {boolean} - By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
* @param [options.separators] {boolean} - Put `<hr>` breaks between identifiers. Improves readability on bulky docs.
* @param [options.module-index-format] {string} - none, grouped, table, dl.
* @param [options.global-index-format] {} - none, grouped, table, dl.
* @param [options.param-list-format] {} - Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.
* @param [options.property-list-format] {} - list, table.
* @param [options.member-index-format] {} - grouped, list
* @return {Promise}

@@ -47,5 +61,5 @@ * @fulfil {string} - the rendered docs

/**
* Returns markdown documentation from jsdoc-annoted source code.
* Sync version of {@link module:jsdoc-to-markdown#render}.
*
* @param [options] {JsdocOptions | DmdOptions} - the options
* @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#render}.
* @return {string}

@@ -68,5 +82,5 @@ * @engine nodejs >= 0.12

/**
* Returns template data (jsdoc-parse output).
* Returns the template data (jsdoc-parse output) which is fed into the output template (dmd).
*
* @param [options] {JsdocOptions} - the options
* @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}.
* @return {Promise}

@@ -84,5 +98,5 @@ * @fulfil {object[]} - the json data

/**
* Returns template data (jsdoc-parse output).
* Sync version of {@link module:jsdoc-to-markdown#getTemplateData}.
*
* @param [options] {JsdocOptions} - the options
* @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}.
* @return {object[]}

@@ -99,5 +113,10 @@ * @category sync

/**
* Returns raw jsdoc data.
* Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc).
*
* @param [options] {JsdocOptions} - the options
* @param [options] {object} - the options
* @param [options.no-cache] {boolean} - By default results are cached to speed up repeat invocations. Set to true to disable this.
* @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 [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}

@@ -113,5 +132,5 @@ * @fulfil {object[]}

/**
* Returns raw jsdoc data.
* Sync version of {@link module:jsdoc-to-markdown#getJsdocData}.
*
* @param [options] {JsdocOptions} - the options
* @param [options] {object} - Identical options to {@link module:jsdoc-to-markdown#getJsdocData}.
* @return {object[]}

@@ -134,2 +153,8 @@ * @category sync

/**
* 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) {

@@ -136,0 +161,0 @@ return this.getTemplateData(options)

115

src/test/async.js

@@ -14,2 +14,3 @@ 'use strict'

jsdoc2md._usage._lastSentPath = 'tmp-test/lastSent.json'
process.on('beforeExit', () => jsdoc2md._usage.send())

@@ -20,3 +21,3 @@ const runner = new TestRunner()

runner.test('.render({ files })', function () {
return jsdoc2md.render({ files: inputFile, cache: false })
return jsdoc2md.render({ files: inputFile })
.then(result => a.ok(/a visible global/.test(result)))

@@ -28,30 +29,30 @@ })

{
"id": "visible",
"longname": "visible",
"name": "visible",
"kind": "member",
"scope": "global",
"description": "a visible global",
"meta": {
"lineno": 4,
"filename": "ignore.js"
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
"order": 0
order: 0
},
{
"id": "invisible",
"longname": "invisible",
"name": "invisible",
"kind": "member",
"scope": "global",
"description": "an ignored global",
"ignore": true,
"meta": {
"lineno": 10,
"filename": "ignore.js"
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
"order": 1
order: 1
}
]
return jsdoc2md.render({ data: data, cache: false })
return jsdoc2md.render({ data: data })
.then(result => a.ok(/a visible global/.test(result)))

@@ -61,3 +62,3 @@ })

runner.test('.render({ files, heading-depth: 4 })', function () {
return jsdoc2md.render({ files: inputFile, cache: false, 'heading-depth': 4 })
return jsdoc2md.render({ files: inputFile, 'heading-depth': 4 })
.then(result => a.ok(/#### visible/.test(result)))

@@ -68,3 +69,3 @@ })

const inputFile = 'src/test/fixture/params.js'
return jsdoc2md.render({ files: inputFile, cache: false, 'param-list-format': 'list' })
return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list' })
.then(result => a.ok(/- one/.test(result)))

@@ -74,3 +75,3 @@ })

runner.test('.getTemplateData({ files })', function () {
return jsdoc2md.getTemplateData({ files: inputFile, cache: false })
return jsdoc2md.getTemplateData({ files: inputFile })
.then(result => a.ok(result[0].id))

@@ -80,4 +81,64 @@ })

runner.test('.getJsdocData({ files })', function () {
return jsdoc2md.getJsdocData({ files: inputFile, cache: false })
return jsdoc2md.getJsdocData({ files: inputFile })
.then(result => a.ok(result[0].longname))
})
runner.test('.render({ files, noCache })', function () {
return jsdoc2md.render({ files: inputFile, noCache: true })
.then(result => a.ok(/a visible global/.test(result)))
})
runner.test('.render({ data, noCache })', function () {
const data = [
{
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
order: 0
},
{
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
order: 1
}
]
return jsdoc2md.render({ data: data, noCache: true })
.then(result => a.ok(/a visible global/.test(result)))
})
runner.test('.render({ files, heading-depth: 4, noCache })', function () {
return jsdoc2md.render({ files: inputFile, 'heading-depth': 4, noCache: true })
.then(result => a.ok(/#### visible/.test(result)))
})
runner.test('.render({ files, param-list-format: list, noCache })', function () {
const inputFile = 'src/test/fixture/params.js'
return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list', noCache: true })
.then(result => a.ok(/- one/.test(result)))
})
runner.test('.getTemplateData({ files, noCache })', function () {
return jsdoc2md.getTemplateData({ files: inputFile, noCache: true })
.then(result => a.ok(result[0].id))
})
runner.test('.getJsdocData({ files, noCache })', function () {
return jsdoc2md.getJsdocData({ files: inputFile, noCache: true })
.then(result => a.ok(result[0].longname))
})

47

src/test/sync.js

@@ -8,3 +8,2 @@ 'use strict'

const a = require('assert')
const path = require('path')
const fs = require('fs')

@@ -17,6 +16,2 @@

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

@@ -33,27 +28,27 @@ const inputFile = 'src/test/fixture/ignore.js'

{
"id": "visible",
"longname": "visible",
"name": "visible",
"kind": "member",
"scope": "global",
"description": "a visible global",
"meta": {
"lineno": 4,
"filename": "ignore.js"
id: 'visible',
longname: 'visible',
name: 'visible',
kind: 'member',
scope: 'global',
description: 'a visible global',
meta: {
lineno: 4,
filename: 'ignore.js'
},
"order": 0
order: 0
},
{
"id": "invisible",
"longname": "invisible",
"name": "invisible",
"kind": "member",
"scope": "global",
"description": "an ignored global",
"ignore": true,
"meta": {
"lineno": 10,
"filename": "ignore.js"
id: 'invisible',
longname: 'invisible',
name: 'invisible',
kind: 'member',
scope: 'global',
description: 'an ignored global',
ignore: true,
meta: {
lineno: 10,
filename: 'ignore.js'
},
"order": 1
order: 1
}

@@ -60,0 +55,0 @@ ]

jsdoc2md/API.hbs

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc