jsdoc2md/jsdoc-api

A programmatic interface for jsdoc3 with a few extra features

jsdoc-api

A programmatic interface for jsdoc3 with a few features:

• Sync and async (Promise) interfaces on the two main jsdoc operations ('explain' and 'render documentation').
• Input (source code) can supplied as a string or set of file names/globs.
• Optional caching, dramatically speeding up future invocations with the same input.

Synopsis

> const jsdoc = require('jsdoc-api')

> jsdoc.explainSync({ source: '/** example doclet */ \n var example = true' })
[ { comment: '/** example doclet *∕',
   meta:
    { range: [ 28, 42 ],
      filename: 'nkrf18zlymohia4i29a0zkyt84obt9.js',
      lineno: 2,
      path: '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T',
      code:
       { id: 'astnode100000002',
         name: 'example',
         type: 'Literal',
         value: true } },
   description: 'example doclet',
   name: 'example',
   longname: 'example',
   kind: 'member',
   scope: 'global' },
 { kind: 'package',
   longname: 'package:undefined',
   files: [ '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T/nkrf18zlymohia4i29a0zkyt84obt9.js' ] } ]

API Reference

• jsdoc-api
  • static
    • .cache : cache-point
    • .explainSync([options]) ⇒ Array.<object>
    • .explain([options]) ⇒ Promise
    • .renderSync([options])
  • inner
    • ~JsdocOptions
      • .files : string | Array.<string>
      • .source : string
      • .cache : boolean
      • .access : string
      • .configure : string
      • .destination : string
      • .encoding : string
      • .private : boolean
      • .package : string
      • .pedantic : boolean
      • .query : string
      • .recurse : boolean
      • .readme : string
      • .template : string
      • .tutorials : string

jsdoc.cache : cache-point

The cache-point instance used when cache: true is specified on .explain() or .explainSync().

Kind: static property of jsdoc-api

jsdoc.explainSync([options]) ⇒ Array.<object>

Returns jsdoc explain output.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

Param	Type
[options]	JsdocOptions

jsdoc.explain([options]) ⇒ Promise

Returns a promise for the jsdoc explain output.

Kind: static method of jsdoc-api
Fulfil: object[] - jsdoc explain output

Param	Type
[options]	JsdocOptions

jsdoc.renderSync([options])

Render jsdoc documentation.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

Param	Type
[options]	JsdocOptions

Example

jsdoc.renderSync({ files: 'lib/*', destination: 'api-docs' })

jsdoc-api~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

• ~JsdocOptions
  • .files : string | Array.<string>
  • .source : string
  • .cache : boolean
  • .access : string
  • .configure : string
  • .destination : string
  • .encoding : string
  • .private : boolean
  • .package : string
  • .pedantic : boolean
  • .query : string
  • .recurse : boolean
  • .readme : string
  • .template : string
  • .tutorials : string

options.files : string | Array.<string>

One or more filenames to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.source : string

A string containing source code to process. Either this or files must be supplied.

Kind: instance property of JsdocOptions

options.cache : boolean

Set to true to cache the output - future invocations with the same input will return immediately.

Kind: instance property of JsdocOptions

options.access : string

Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".

Kind: instance property of JsdocOptions

options.configure : string

The path to the configuration file. Default: path/to/jsdoc/conf.json.

Kind: instance property of JsdocOptions

options.destination : string

The path to the output folder. Use "console" to dump data to the console. Default: ./out/.

Kind: instance property of JsdocOptions

options.encoding : string

Assume this encoding when reading all source files. Default: utf8.

Kind: instance property of JsdocOptions

options.private : boolean

Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.

Kind: instance property of JsdocOptions

options.package : string

The path to the project's package file. Default: path/to/sourcefiles/package.json

Kind: instance property of JsdocOptions

options.pedantic : boolean

Treat errors as fatal errors, and treat warnings as errors. Default: false.

Kind: instance property of JsdocOptions

options.query : string

A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.

Kind: instance property of JsdocOptions

options.recurse : boolean

Recurse into subdirectories when scanning for source files and tutorials.

Kind: instance property of JsdocOptions

options.readme : string

The path to the project's README file. Default: path/to/sourcefiles/README.md.

Kind: instance property of JsdocOptions

options.template : string

The path to the template to use. Default: path/to/jsdoc/templates/default.

Kind: instance property of JsdocOptions

options.tutorials : string

Directory in which JSDoc should search for tutorials.

Kind: instance property of JsdocOptions

---

© 2015-23 Lloyd Brookes <[email protected]>.

Tested by test-runner. Documented by jsdoc-to-markdown.

jsdoc-api's Issues

'undocumented' parameter

I'm checking the result from parsing javascript file with explainSync, and seems undocumented parameter means whether this has been documented or not:

[
...
  },
  {
    ...
    name: "docName",
    undocumented: true,
    kind: "function",
  }
{
...
]

But when there are documents information, this undocumented key are not exists, instead of showing undocumented: false.

Would it be better to set this value when document exists?

Thanks.

.files or .source options should be optional if .configure is set

Currently, if one passes in the path to a configuration file via the configure option we still get this error message:

Must set either .files or .source options

If the configuration file already specifies one of these, it shouldn't be mandatory to repeat them.

Error when just parsing comments

I'm using esprima and I've the need of parsing comments. Esprima conveniently provides an array with comments which I'll use along with the jsdoc-api to extract useful info.

Thing is, when using explainSync (and probably other methods but I've only tested explainSync), if only the comment is provided the results are unexpected.

console.log(jsdoc.explainSync({ source: '/** example doclet */ \n var example = true' })); 
//Outputs as expected.

console.log(jsdoc.explainSync({ source: '/** example doclet */' }));  
/* Outputs:
[ { kind: 'package',
    longname: 'package:undefined',
    files: [ '/tmp/ebm4dtq81kqhbyb9aa2p72j45l3gcik9.js' ] } ]
*/

Is this expected behaviour?

"There are no input files to process" error from explainSync()

I am attempting to pass file contents that I retrieved by calling the GitHub API into explainSync. When I was previously reading a local file using fs.readFileSync(<file_path>).toString() and passing this into explainSync, it worked. However, now when I am doing the following, I get the error "There are no input files to process".

const sourceCode = Buffer.from(<fileContents>, 'base64').toString();
const documentationBlocks = explainSync({ source: sourceCode });

I verified that sourceCode is a string that contains the contents of the file that I wish to parse the documentation of.

I have also tried passing in a plain string to explainSync without creating a Buffer and converting it to a string, and the plain string approach gives the same error.

Does anyone know of a solution to fix this?

`EMFILE: too many open files` when not using --no-cache

If the number of files in this.inputFileSet.files is large enough, readCache() reaches the user's limit and rejects with an error. The error is swallowed in getOutput(), which manifests in a very strange message: Error: Cannot find module 'collect-all', even though that package is installed. (This seems to be the next time something tries to access the filesystem.)

Is there any interest in exploring graceful-fs here or in another module to solve caching for very large numbers of files? Or any other suggested solutions? For now, my workaround is to use --no-cache, which works, but costs more time.

I'd be happy to throw a PR together, either way.

JSDOC_ERROR when running README example

When I run jsdoc.explainSync({ source: '/** example doclet *∕ \n var example = true' }) from the README, I get this error:

     JSDOC_ERROR: ERROR: Unable to parse /var/folders/g1/kj7f1k4973l0fd3c2mjnf9j80000gp/T/7pdqccagq0n51cn39ozmxfajorl4by2ka8czrrqa8n8uygmn29.js: Line 2: Unexpected token ILLEGAL
      at ExplainSync.verifyOutput (node_modules/jsdoc-api/lib/jsdoc-command.js:114:19)

jsdoc-to-markdown fails with ENOBUFS

This is the same issue as reported in #21
I'm running into this issue even after I have upgraded to 6.0.1. I'm using Node v14.15.4 on Windows 10. Not sure about other projects but our src is somewhat large. I can see when I debug the spawned jsdoc process, that jsdoc is trying to deal with roughly 85K doclets.
I can also see when watching the Memory heap size in Chrome DevTools that the memory size for the spawned process goes up to 850MByte so the default maxBuffer setting for the spawned process (20M) is not nearly enough.
If I mess around with jsdoc-api/lib/explain-sync and update the maxBuffer to 1G (maxBuffer: 1024 * 1024 * 1024) then my process finishes as expected.
Not sure what to do at this point. Up until now, we used jsdoc 3.4 with Node version < 12. But we had to upgrade Node to LTS version however the upgrade also forced us to upgrade jsdoc to 3.6. Now our process to generate JSON from doclets is broken.
Does it make sense to allow setting the maxBuffer size as an env variable?

@see with inline @link not parsed

Issue

When parsing a bloc of comment containing nested @link in a @see, the see key in the output gives raw links instead of parsing the name of the link and the url.

How to reproduce

Try to parse this following comment:

/**
  * Returns the first (or first nth) element(s) of the array.     * 
  * @param {Integer} options.count=1 - number of element to return
  * @return {*}
  * @throws {Error} if the option "count" is not an integer
  * @since 0.1.0
  * @see {@link https://github.com|View source}
  * @see {@link https://github.com|View tests}
  */

Expected value

Something like:

see:
  [ links: [  { url: 'https://github.com',
                name: 'View source' },
              { url: 'https://github.com',
                name: 'View tests' } ] ]

Actual value

see:
   [ '{@link https://github.com|View source}',
     '{@link https://github.com|View tests}' ]

Version used to fill this issue

4.0.3

jsdoc-to-markdown fails with ENOBUFS error when renderSync

JSDoc-api fails with output parse error cause stdout is out of buffer and result is not full (spawnSync process is killed by SIGTERM)

Expected behavior

jsdoc-to-markdown generate docs w/o errors, it can be aimed by increasing maxBuffer option in jsdoc spawnSync call

Current behavior

crash

Your environment

Software	Version
JSDoc	master
Node.js	12.16
npm	6.14
Operating system	Windows / Ubuntu / Fedora

Path of temporary file contains underscore, no files to process

We're running into an issue where we randomly get "There are no input files to process" errors.

Initially files run through https://github.com/jsdoc2md/gulp-jsdoc-to-markdown. At some point the following command is executed: jsdoc -X /var/folders/dx/_yc89prs1fq_g81m07nqjjy00000gn/T/t5v3v4ty2pvjblis4mbdibe2920pl85ipt5rz0afwkpy76cg14i.js.

This fails, because jsdoc's file parser contains an excludePattern matching underscores at the beginning of files and seemingly also folders.

There are at least three options how to solve this:

1. Pass a config file to jsdoc using -c, see here: jsdoc/jsdoc#1155
2. Make sure the temporary path doesn't contain leading underscores
3. Fix jsdoc itself to only match leading underscores at the beginning of files, but not folders

Let me know if I can be of any help here.

Failed to include an async function

Hello,
When I add an async function, the explainSync method fails, this is the case

var jsdocApi = require("jsdoc-api");

console.log(jsdocApi.explainSync({ source: `
/** example doclet */
var example = true

async function onSubmit () {
    console.log('example')
}
` }))

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
Appreciate your help. Thanks.

"JSDOC_ERROR: Jsdoc failed." too vague

when jsdoc fails it doesn't always throw an exception or exit with a code > 0.. still, need to figure out the error and report a more useful message

ES6 export default class has wrong name and longname

When using source export default class MyClassName {} the extracted name and longname are not correct ('exports' and 'module.exports' respectively).
This does not seem to happen when using export default after the class declaration or non-default exports.

Check the code here https://runkit.com/embed/5008rb12y6pr

var jsdocApi = require("jsdoc-api")
jsdocApi.explain({ source: `/**
 * Lorem ipsum
 * @summary Foo bar baz
 */
export default class LoremIpsum {}

/**
 * Dolor sit
 * @summary Qux baz click
 */
class DolorSit {}

export {DolorSit};

/**
 * Foo Bar
 * @summary Lorem lorem lorem
 */
export class FooBar {}` }).then(console.log.bind(console));

JSDOC_ERROR: ERROR: Unable to parse file ...

environment:

win10
jsdoc3
node 10.15.3

project setup

E:\_dev\_jsstack\own-casino\routing:
  jsdoc2md.js
  config.js

jsdoc2md.js:

const jsdoc = require('jsdoc-api');

let res = jsdoc.explainSync({
  files: ['./config.js'],
  source: {
    excludePattern: null
  }
});
console.log(res);

the Problem

as i found out few days ago when tested jsdocs CLI, they have default excludePattern
"excludePattern": "(^|\\/|\\\\)_"
This prevent to process any file if there is an underscore in the path (say folder name starts with underscore)
the default jsdoc cli returns an error: JSDOC_ERROR: There are no input files to process
so, i have to use CLI with custom config where i can setup this excludePattern and in that case everything is working good.

Same thing happens when i tried jsdoc-api.
In first place i got exception "There are no input files to process"
then i tried redefine default excludePattern and now i am getting this error:

E:\_dev\_jsstack\own-casino\routing\node_modules\jsdoc-api\lib\jsdoc-command.js:114
      throw err
      ^

JSDOC_ERROR: ERROR: Unable to parse C:\Users\dim\AppData\Local\Temp\nzib7okrirep26r717gm9.js: Unexpected token, expected "," (1:8)

what you can suggest me?

with best regards

verifyOutput error

It seems that verifyOutput (code, output) { is broken when using multiple files in command line
It tries to JSON.parse debugging that make the JSON.parse fail

'Parsing /Users/lx0/Sites/api/local_modules/api_helper.js ...\nParsing /Users/lx0/Sites/api/local_modules/file_helper.js ...\nParsing /Users/lx0/Sites/api/local_modules/generic_api_class.js ...\nParsing /Users/lx0/Sites/api/local_modules/generic_csv_api_class.js ...\nParsing  ...\n[\n    {\n        "comment": "",\n        "meta":

From: node debug node_modules/jsdoc-to-markdown/bin/cli.js --no-cache -c jsdoc.json --files "./!(node_modules)/**.js"

"access" option is not working

I'm using the API for parsing my source code, and sometimes I'm just interested in the private symbols, so I'm using the explainSync method like:

const result = jsdoc.explainSync({
  files: [...],
  access: 'private'
});

But always the results are the same, either with or without access: 'private'

So I looked in the source-code, and I didn't see any place using the access option
https://github.com/jsdoc2md/jsdoc-api/blob/master/lib/jsdoc-command.js#L47
https://github.com/jsdoc2md/jsdoc-api/search?l=JavaScript&q=access&utf8=%E2%9C%93

child process on close event fires too early in jsdoc-api/lib/explain.js:Explain#_runJsdoc

Hello,
in my project i'm using "jsdoc-parse" to analyze some JSDoc at runtime.
To process the data, i'am using the parser in stream-pipe with some manipulation transform and finally collect it as object data with "stream-collect" to return a promise:

    return jsdocParse({
      'src': [
        jsdocCommonArgumentsPath,
        jsdocArgumentsPath
      ],
      'stats': false,
      'html': false
    })
      .pipe(JSONStream.parse('*'))
      .pipe(new ReduceJSDocArgumentsObjectStreamTransform)
      .pipe(collect.objectStream())
      .then(function mergeResult(res) {
        return _.concat.apply(this, res);
      });

That works just fine as long it's working at all. But i've found out, that in jsdoc-api/lib/explain.js the method _runJSdoc has a problem. In this method the stdout and stderr -streams are collected and after spawn a "node"-child-process with jsdoc-75lb and params, the collected data is processed on handle.on('close'). But this is fired sometimes too early and the stdout data is not collected yet. In such a case the stdout is empty and the "verifyOutput"-method fails at parsing the empty content with JSON.parse.

My tested working suggestion is as following:

  _runJsdoc() {
    let _this = this;

    return new Promise((resolve, reject) => {
      const collectAll = require('collect-all');

      // Important! Not listen only to handle.on('close')-event, stdout.on('end') can fire after it 
      // and thus it's possible that stdout-data is not fully collected yet.
      let isStderrEnd = false;
      let isStdoutEnd = false;
      let isProcessClose = false;
      let processCloseCode = 0;

      function finished() {
        if (isStderrEnd && isStdoutEnd && isProcessClose) {
          setTimeout(() => {
            try {
              const explainOutput = _this.verifyOutput(processCloseCode, jsdocOutput);
              if (_this.options.cache) {
                _this.cache.write(_this.cacheKey, explainOutput).then(() => resolve(explainOutput))
              } else {
                resolve(explainOutput)
              }
            } catch (err) {
              reject(err)
            }
          });
        }
      }

      const jsdocOutput = {
        'stdout': '',
        'stderr': '',
        collectInto (dest) {
          return collectAll(data => {
            this[dest] = data.toString();
          })
        }
      };

      const toSpawnArgs = require('object-to-spawn-args');
      const jsdocArgs = toSpawnArgs(_this.jsdocOptions).concat(['-X'])
        .concat(_this.options.source ? _this.tempFile.path : _this.inputFileSet.files);
      jsdocArgs.unshift(_this.jsdocPath);

      const spawn = require('child_process').spawn;
      const handle = spawn('node', jsdocArgs);

      handle.stderr.on('end', () => {
        isStderrEnd = true;
        finished();
      });
      handle.stdout.on('end', () => {
        isStdoutEnd = true;
        finished();
      });
      handle.on('close', (code) => {
        processCloseCode = code;
        isProcessClose = true;
        finished();
      });
      handle.stderr.pipe(jsdocOutput.collectInto('stderr'));
      handle.stdout.pipe(jsdocOutput.collectInto('stdout'));
    })
  }

I'm using nodejs v4.5.0 on Windows x64.

Best regards,
Manusan

Make .source .files optional when config file specified

When the configuration file is specified, wouldn't it be better to assume that input sources are handled? Otherwise one has to explicitly specify files or source only to be overridden by the ones in config.

Explicitly setting pedantic to false generates error

As I experimented with JSDoc API, I tried the following code:

const jsdoc = require('jsdoc-api')
jsdoc.explainSync({files: 'functions/engine/scenarios.js', pedantic: false});

Unfortunately, that throws an error, where it seems as if false has been mistaken for a path.

/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/lib/jsdoc-command.js:114
      throw err
      ^

JSDOC_ERROR: ERROR: Unable to find the source file or directory /Users/martin/dev/src/fictive-tools/false
    at ExplainSync.verifyOutput (/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/lib/jsdoc-command.js:112:19)
    at ExplainSync._runJsdoc (/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/lib/explain-sync.js:34:32)
    at ExplainSync.getOutput (/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/lib/explain-sync.js:17:19)
    at ExplainSync.execute (/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/lib/jsdoc-command.js:49:24)
    at Object.explainSync (/Users/martin/dev/src/fictive-tools/node_modules/jsdoc-api/index.js:20:18)
    at Object.<anonymous> (/Users/martin/dev/src/fictive-tools/test.js:2:7)
    at Module._compile (internal/modules/cjs/loader.js:1185:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1205:10)
    at Module.load (internal/modules/cjs/loader.js:1034:32)
    at Function.Module._load (internal/modules/cjs/loader.js:923:14)

Calling with true works, however.

Thanks,
Martin