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.

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.

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

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

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.

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

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?

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

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?

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"

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.

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

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?

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)

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

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.

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.

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

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