Skip to content

Commit

Permalink
update API docs
Browse files Browse the repository at this point in the history
75lb committed Sep 2, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent e4f72ee commit df1db5a
Showing 3 changed files with 45 additions and 42 deletions.
27 changes: 14 additions & 13 deletions dist/index.cjs
Original file line number Diff line number Diff line change
@@ -28,7 +28,7 @@ class JsdocOptions {
/**
* @module jsdoc-to-markdown
* @example
* const jsdoc2md = require('jsdoc-to-markdown')
* import jsdoc2md from 'jsdoc-to-markdown'
*/

/**
@@ -40,8 +40,8 @@ class JsdocToMarkdown {
* Returns markdown documentation from jsdoc-annoted source code.
*
* @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.data] {object[]} - Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData()`. In the options, one of `files`, `source`, , `configure` or `data` must be supplied.
* @param [options.template] {string} - The handlebars template the supplied documentation will be rendered into. Enables 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.
@@ -55,15 +55,16 @@ class JsdocToMarkdown {
* @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
* @param [options.clever-links] {boolean} - If true, then implements jsdoc 'cleverLinks' algorithm; `{@link}` tags captions with a URL link are rendered in plain text and captions with non-URL links are rendered in monospace.
* @param [options.monospace-links] {boolean} - If true, then `{@link}` tags are rendered in monospace. This option is ignored if `clever-links` is true.
* @return {Promise}
* @param [options.clever-links] {boolean} - By default, all {@link} tags are rendered in plain text. If `--clever-links` is set, URL {@link} tags are rendered in plain text, otherwise monospace.
* @param [options.monospace-links] {boolean} - By default, all {@link} tags are rendered in plain text. If `--monospace-links` is set, all links are rendered in monospace format. This setting is ignored if `--clever-links` is set.
* @param [options.EOL] {string} - Specify ether `posix` or `win32`. Forces all line endings in the dmd output to use the specified EOL character - can help to avoid scenarios where files contain mixed line-endings.
* @return {Promise<string>}
* @fulfil {string} - the rendered docs
* @category async
* @example
* Pass in filepaths (`**` glob matching supported) of javascript source files:
* ```js
* > jsdoc2md.render({ files: 'lib/*.js' }).then(console.log)
* > const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' })
* ```
*/
async render (options = {}) {
@@ -80,7 +81,7 @@ class JsdocToMarkdown {
* 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}
* @return {Promise<object[]>}
* @fulfil {object[]} - the json data
* @category async
*/
@@ -93,11 +94,11 @@ class JsdocToMarkdown {
* Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc).
*
* @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](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json.
* @return {Promise}
* @param [options.no-cache] {boolean} - By default results are cached to speed up repeat invocations with the same input. 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 `configure` must be supplied.
* @param [options.source] {string} - A string containing source code to process. One of `files`, `source` or `configure` must be supplied.
* @param [options.configure] {string} - The path to the [jsdoc configuration file](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. One of `files`, `source` or `configure` must be supplied.
* @return {Promise<object[]>}
* @fulfil {object[]}
* @category async
*/
33 changes: 17 additions & 16 deletions docs/API.md
Original file line number Diff line number Diff line change
@@ -3,14 +3,14 @@
# jsdoc-to-markdown
**Example**
```js
const jsdoc2md = require('jsdoc-to-markdown')
import jsdoc2md from 'jsdoc-to-markdown'
```

* [jsdoc-to-markdown](#module_jsdoc-to-markdown)
* [JsdocToMarkdown](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)
* [.render([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+render) ⇒ <code>Promise</code>
* [.getTemplateData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData) ⇒ <code>Promise</code>
* [.getJsdocData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData) ⇒ <code>Promise</code>
* [.render([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+render) ⇒ <code>Promise.&lt;string&gt;</code>
* [.getTemplateData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData) ⇒ <code>Promise.&lt;Array.&lt;object&gt;&gt;</code>
* [.getJsdocData([options])](#module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData) ⇒ <code>Promise.&lt;Array.&lt;object&gt;&gt;</code>
* [.clear()](#module_jsdoc-to-markdown--JsdocToMarkdown+clear) ⇒ <code>Promise</code>
* [.getNamepaths(options)](#module_jsdoc-to-markdown--JsdocToMarkdown+getNamepaths) ⇒ <code>object</code>

@@ -20,7 +20,7 @@ const jsdoc2md = require('jsdoc-to-markdown')
**Kind**: Exported class
<a name="module_jsdoc-to-markdown--JsdocToMarkdown+render"></a>

### jsdoc2md.render([options]) ⇒ <code>Promise</code>
### jsdoc2md.render([options]) ⇒ <code>Promise.&lt;string&gt;</code>
Returns markdown documentation from jsdoc-annoted source code.

**Kind**: instance method of [<code>JsdocToMarkdown</code>](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)
@@ -30,8 +30,8 @@ Returns markdown documentation from jsdoc-annoted source code.
| Param | Type | Description |
| --- | --- | --- |
| [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.data] | <code>Array.&lt;object&gt;</code> | Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData()`. In the options, one of `files`, `source`, , `configure` or `data` must be supplied. |
| [options.template] | <code>string</code> | The handlebars template the supplied documentation will be rendered into. Enables 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> \| <code>Array.&lt;string&gt;</code> | Use an installed package containing helper and/or partial overrides. |
@@ -45,17 +45,18 @@ Returns markdown documentation from jsdoc-annoted source code.
| [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 |
| [options.clever-links] | <code>boolean</code> | If true, then implements jsdoc 'cleverLinks' algorithm; `{@link}` tags captions with a URL link are rendered in plain text and captions with non-URL links are rendered in monospace. |
| [options.monospace-links] | <code>boolean</code> | If true, then `{@link}` tags are rendered in monospace. This option is ignored if `clever-links` is true. |
| [options.clever-links] | <code>boolean</code> | By default, all {@link} tags are rendered in plain text. If `--clever-links` is set, URL {@link} tags are rendered in plain text, otherwise monospace. |
| [options.monospace-links] | <code>boolean</code> | By default, all {@link} tags are rendered in plain text. If `--monospace-links` is set, all links are rendered in monospace format. This setting is ignored if `--clever-links` is set. |
| [options.EOL] | <code>string</code> | Specify ether `posix` or `win32`. Forces all line endings in the dmd output to use the specified EOL character - can help to avoid scenarios where files contain mixed line-endings. |

**Example**
Pass in filepaths (`**` glob matching supported) of javascript source files:
```js
> jsdoc2md.render({ files: 'lib/*.js' }).then(console.log)
> const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' })
```
<a name="module_jsdoc-to-markdown--JsdocToMarkdown+getTemplateData"></a>

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

**Kind**: instance method of [<code>JsdocToMarkdown</code>](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)
@@ -68,7 +69,7 @@ Returns the template data (jsdoc-parse output) which is fed into the output temp

<a name="module_jsdoc-to-markdown--JsdocToMarkdown+getJsdocData"></a>

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

**Kind**: instance method of [<code>JsdocToMarkdown</code>](#exp_module_jsdoc-to-markdown--JsdocToMarkdown)
@@ -78,10 +79,10 @@ Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/j
| Param | Type | Description |
| --- | --- | --- |
| [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> \| <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](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. |
| [options.no-cache] | <code>boolean</code> | By default results are cached to speed up repeat invocations with the same input. Set to true to disable this. |
| [options.files] | <code>string</code> \| <code>Array.&lt;string&gt;</code> | One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `configure` must be supplied. |
| [options.source] | <code>string</code> | A string containing source code to process. One of `files`, `source` or `configure` must be supplied. |
| [options.configure] | <code>string</code> | The path to the [jsdoc configuration file](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. One of `files`, `source` or `configure` must be supplied. |

<a name="module_jsdoc-to-markdown--JsdocToMarkdown+clear"></a>

27 changes: 14 additions & 13 deletions index.js
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@ import jsdocParse from 'jsdoc-parse'
/**
* @module jsdoc-to-markdown
* @example
* const jsdoc2md = require('jsdoc-to-markdown')
* import jsdoc2md from 'jsdoc-to-markdown'
*/

/**
@@ -19,8 +19,8 @@ class JsdocToMarkdown {
* Returns markdown documentation from jsdoc-annoted source code.
*
* @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.data] {object[]} - Raw template data to use. Useful when you already have template data, obtained from `.getTemplateData()`. In the options, one of `files`, `source`, , `configure` or `data` must be supplied.
* @param [options.template] {string} - The handlebars template the supplied documentation will be rendered into. Enables 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.
@@ -34,15 +34,16 @@ class JsdocToMarkdown {
* @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
* @param [options.clever-links] {boolean} - If true, then implements jsdoc 'cleverLinks' algorithm; `{@link}` tags captions with a URL link are rendered in plain text and captions with non-URL links are rendered in monospace.
* @param [options.monospace-links] {boolean} - If true, then `{@link}` tags are rendered in monospace. This option is ignored if `clever-links` is true.
* @return {Promise}
* @param [options.clever-links] {boolean} - By default, all {@link} tags are rendered in plain text. If `--clever-links` is set, URL {@link} tags are rendered in plain text, otherwise monospace.
* @param [options.monospace-links] {boolean} - By default, all {@link} tags are rendered in plain text. If `--monospace-links` is set, all links are rendered in monospace format. This setting is ignored if `--clever-links` is set.
* @param [options.EOL] {string} - Specify ether `posix` or `win32`. Forces all line endings in the dmd output to use the specified EOL character - can help to avoid scenarios where files contain mixed line-endings.
* @return {Promise<string>}
* @fulfil {string} - the rendered docs
* @category async
* @example
* Pass in filepaths (`**` glob matching supported) of javascript source files:
* ```js
* > jsdoc2md.render({ files: 'lib/*.js' }).then(console.log)
* > const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' })
* ```
*/
async render (options = {}) {
@@ -59,7 +60,7 @@ class JsdocToMarkdown {
* 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}
* @return {Promise<object[]>}
* @fulfil {object[]} - the json data
* @category async
*/
@@ -72,11 +73,11 @@ class JsdocToMarkdown {
* Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc).
*
* @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](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json.
* @return {Promise}
* @param [options.no-cache] {boolean} - By default results are cached to speed up repeat invocations with the same input. 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 `configure` must be supplied.
* @param [options.source] {string} - A string containing source code to process. One of `files`, `source` or `configure` must be supplied.
* @param [options.configure] {string} - The path to the [jsdoc configuration file](https://jsdoc.app/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. One of `files`, `source` or `configure` must be supplied.
* @return {Promise<object[]>}
* @fulfil {object[]}
* @category async
*/

0 comments on commit df1db5a

Please sign in to comment.