jsdoc2md / jsdoc-to-markdown

Generate markdown documentation from jsdoc-annotated javascript
MIT License
1.69k stars 152 forks source link

`getTemplateDataSync` breaks program when file amount is too many with "WARNING: The @ignore tag does not permit a value; the value will be ignored ... at ExplainSync.verifyOutput" #278

Closed samgermain closed 2 months ago

samgermain commented 2 years ago

I couldn't find an example of how to use jsdoc2md for every file in a folder, so I'm using it for every class in a folder of files (preferably I'd like to just do it for every file in a folder)

This is my code

'use strict'
const jsdoc2md = require('jsdoc-to-markdown')
const fs = require('fs')
const path = require('path')

/* input and output paths */
const outputDir = './wiki/exchange-specific-docs'

/* get template data */
const files = fs.readdirSync("./js").filter(file => path.extname(file) == '.js').map(file => `./js/${file}`)

const templateData = jsdoc2md.getTemplateDataSync({ files: files })

/* reduce templateData to an array of class names */
const classNames = templateData.reduce((classNames, identifier) => {
  if (identifier.kind === 'class') classNames.push(identifier.name)
  return classNames
}, [])

/* create a documentation file for each class */
for (const className of classNames) {
  const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
  console.log(`rendering ${className}, template: ${template}`)
  const output = jsdoc2md.renderSync({ data: templateData, template: template })
  fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output)
}

when I run it with files being the full list of files (about 120) I get the error

/path/ccxt/node_modules/jsdoc-api/lib/jsdoc-command.js:114
      throw err
      ^

JSDOC_ERROR: Debugger listening on ws://127.0.0.1:38320.ofjioja-alsfoiejww2-asldfjja
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: aax.js, line: 2332
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: aax.js, line: 2360
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: ascendex.js, line: 2362
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: ascendex.js, line: 2390
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: binance.js, line: 4841
WARNING: The @ignore tag does not permit a value; the value will be ignored. File: binance.js, line: 4862
    at ExplainSync.verifyOutput (/path/ccxt/node_modules/jsdoc-api/lib/jsdoc-command.js:112:19)
    at ExplainSync._runJsdoc (/path/ccxt/node_modules/jsdoc-api/lib/explain-sync.js:34:32)
    at ExplainSync.getOutput (/path/ccxt/node_modules/jsdoc-api/lib/explain-sync.js:12:21)
    at ExplainSync.execute (/path/ccxt/node_modules/jsdoc-api/lib/jsdoc-command.js:49:24)
    at Object.explainSync (/path/ccxt/node_modules/jsdoc-api/index.js:20:18)
    at JsdocToMarkdown.getJsdocDataSync (/path/ccxt/node_modules/jsdoc-to-markdown/index.js:131:21)
    at JsdocToMarkdown.getTemplateDataSync (/path/ccxt/node_modules/jsdoc-to-markdown/index.js:101:28)
    at Object.<anonymous> (/path/ccxt/jsdoc2md.js:131:31)
    at Module._compile (internal/modules/cjs/loader.js:1068:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1097:10)

The program works however, if I split my array into 20 item chunks

'use strict'
const jsdoc2md = require('jsdoc-to-markdown')
const fs = require('fs')
const path = require('path')

function splitArray (array) {
  const arrays = []
  const chunkSize = 20;
  for (let i = 0; i < array.length; i += chunkSize) {
    arrays.push (array.slice (i, i + chunkSize));
  }
  return arrays;
}

/* input and output paths */
const outputDir = './wiki/exchange-specific-docs'

/* get template data */
const files = fs.readdirSync("./js").filter(file => path.extname(file) == '.js').map(file => `./js/${file}`)

const exchanges = splitArray(files);
exchanges.forEach(exchangeList =>  {
  const templateData = jsdoc2md.getTemplateDataSync({ files: exchangeList })

  /* reduce templateData to an array of class names */
  const classNames = templateData.reduce((classNames, identifier) => {
    if (identifier.kind === 'class') classNames.push(identifier.name)
    return classNames
  }, [])

  /* create a documentation file for each class */
  for (const className of classNames) {
    const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
    console.log(`rendering ${className}, template: ${template}`)
    const output = jsdoc2md.renderSync({ data: templateData, template: template })
    fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output)
  }
});
75lb commented 1 year ago

Are you sure the error you are seeing is not related to this line in the output?

JSDOC_ERROR: Debugger listening on ws://127.0.0.1:38320.ofjioja-alsfoiejww2-asldfjja

Does it work if you detach the debugger?