jsdoc-parse

What is jsdoc-parse?

The jsdoc-parse npm package is a tool for parsing JSDoc comments in JavaScript files and generating JSON output. It is useful for extracting documentation information from code comments and can be integrated into documentation generation workflows.

What are jsdoc-parse's main functionalities?

Parsing JSDoc comments

This feature allows you to parse JSDoc comments from JavaScript code and generate a JSON representation of the documentation. The code sample demonstrates how to parse a simple JSDoc comment and output the parsed JSON.

const jsdocParse = require('jsdoc-parse');
const fs = require('fs');

const jsdocComments = `
/**
 * Adds two numbers together.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of the two numbers.
 */
function add(a, b) {
  return a + b;
}
`;

jsdocParse({ src: jsdocComments }).then(output => {
  console.log(JSON.stringify(output, null, 2));
});

Generating JSON output

This feature allows you to generate JSON output from JSDoc comments and save it to a file. The code sample demonstrates how to parse JSDoc comments and write the resulting JSON to a file named 'output.json'.

const jsdocParse = require('jsdoc-parse');
const fs = require('fs');

const jsdocComments = `
/**
 * Multiplies two numbers together.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The product of the two numbers.
 */
function multiply(a, b) {
  return a * b;
}
`;

jsdocParse({ src: jsdocComments }).then(output => {
  fs.writeFileSync('output.json', JSON.stringify(output, null, 2));
});

Other packages similar to jsdoc-parse

documentation

The 'documentation' package is a documentation generation tool that supports JSDoc comments. It can generate HTML, Markdown, and JSON documentation from JavaScript code. Compared to jsdoc-parse, 'documentation' offers more output format options and additional features like linting and serving documentation as a web server.

jsdoc

The 'jsdoc' package is a popular tool for generating HTML documentation from JSDoc comments. It provides a wide range of configuration options and supports plugins for extending its functionality. While jsdoc-parse focuses on parsing and generating JSON output, 'jsdoc' is more comprehensive in terms of generating complete documentation websites.

esdoc

The 'esdoc' package is a documentation generator for JavaScript that supports ES6+ syntax. It provides features like coverage reports, test integration, and a plugin system. Compared to jsdoc-parse, 'esdoc' offers more advanced features and is tailored for modern JavaScript syntax.

README

#jsdoc-parse Jsdoc-annotated javascript source files in, dmd input data out.

##Compatible Platforms Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.

##As a command-line tool Useful for quick access to the data..

###Install

$ npm install -g jsdoc-parse

###Usage

$ jsdoc-parse <src_files>
$ cat <src_files> | jsdoc-parse 

Usage form 2 edge case warning: jsdoc-parse will intepret whatever is piped in as a single file, so take care not to pipe in input containing multipe @modules as this is illegal in jsdoc (see here):

The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.

###Example

$ echo "/** a wonderful global */ var majestic = true;" | jsdoc-parse
[
  {
    "description": "a wonderful global",
    "name": "majestic",
    "longname": "majestic",
    "kind": "member",
    "scope": "global"
  }
]

##As a library For use within node.js.

###Install

$ npm install jsdoc-parse --save

###API Reference Exports a single function (parse) to parse jsdoc data.

Example

var parse = require("jsdoc-parse");

####parse(src, options) ⏏ Documented javascript source files in, doclet data out.

Params

• src string | Array.<string> - source file(s) to parse
• options object - options
  • [stats] boolean - Return stats about the doclets parsed
  • [private] boolean - include @private members in the output

Returns: Stream - a readable stream containing the parsed json data
Example
Code like this:

parse("lib/jsdoc-parse.js").pipe(process.stdout);

would output something like:

[
  {
    "description": "Exports a single function (`parse`) to parse jsdoc data.",
    "kind": "module",
    "name": "jsdoc-parse",
    "examples": [
      "```js\nvar parse = require(\"jsdoc-parse\");\n```"
    ],
    "longname": "module:jsdoc-parse"
  },
  etc,
  etc
]

documented by jsdoc-to-markdown