https://github.com/gr0uch/doc-tree
Documentation generating tool for JavaScript that matches comments to AST nodes.
https://github.com/gr0uch/doc-tree
documentation-tool jsdoc
Last synced: about 1 year ago
JSON representation
Documentation generating tool for JavaScript that matches comments to AST nodes.
- Host: GitHub
- URL: https://github.com/gr0uch/doc-tree
- Owner: gr0uch
- License: gpl-3.0
- Created: 2015-02-02T04:56:11.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-04-16T02:11:46.000Z (about 3 years ago)
- Last Synced: 2025-06-09T20:03:14.107Z (about 1 year ago)
- Topics: documentation-tool, jsdoc
- Language: JavaScript
- Homepage:
- Size: 340 KB
- Stars: 58
- Watchers: 4
- Forks: 6
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# doc-tree
[](https://travis-ci.org/daliwali/doc-tree)
[](https://www.npmjs.com/package/doc-tree)
[](https://raw.githubusercontent.com/daliwali/doc-tree/master/LICENSE)
`doc-tree` parses comments in JavaScript code and outputs the structure and context of the comments in any particular format, JSDoc is the default but any documentation parsing function can be supplied. It traverses the Abstract Syntax Tree (AST) to determine the context of a comment. Basically it's glue code between the AST parser [Acorn](https://github.com/marijnh/acorn), and the JSDoc parser [Doctrine](https://github.com/Constellation/doctrine), though any user-supplied parsing function may be used.
Get it from `npm`:
```sh
$ npm install -g doc-tree
```
## Usage
`doc-tree` operates over `stdio`. Running `doc-tree` on its own source code, and outputting the result to `docs.json`:
```sh
$ doc-tree < lib/index.js > docs.json
```
Or you could use it programmatically, as part of a Node-based build script:
```js
import fs from 'fs'
import docTree from 'doc-tree'
// Parse a string or a buffer.
let doc = docTree.parse(fs.readFileSync('example.js'))
// An array of parsed comments matched with their contexts.
let output = doc.output()
```
The `output` method accepts 2 arguments, a function that accepts a comment and returns anything, and an `options` object to pass to the custom function or the built-in parser, Doctrine.
## Example
This code documentation:
```js
/**
* This is a **Foo** class.
*/
class Foo {
/**
* This is the constructor.
*
* @param {Object} options
*/
constructor (options) { ... }
}
```
Gets outputted as:
```js
[{ comment: { description: '
This is a Foo class.
', tags: [] },
context: { location: { start: [Object], end: [Object] },
name: 'Foo', type: 'class' }
},
{ comment: { description: 'This is the constructor.
', tags: [Object] },
context: { location: { start: [Object], end: [Object] },
type: 'constructor', target: 'Foo' }
}]
```
Descriptions are rendered into HTML using CommonMark. Use `{ render: false }` in the options for `output` to turn it off.
The default JSDoc parser will only consider block comments that start with `/**`.
## License
This software is licensed under the [GNU General Public License v3](https://github.com/daliwali/doc-tree/blob/master/LICENSE).