Can't run API docs locally

Expectation: run the API docs locally

Actual: throws an error

Motivation: to read the API docs 😃

axe-core version: 3.4.0
axe-webdriver, extension or other integration version: N/A

Browser and Assistive Technology versions

For Tooling issues:
- Node version: 12.13.1  
- Platform: Mac 10.14.6  

I’m trying to run the API docs locally as per the docs instructions. I get the following errors:

henrick@henrick-macbookpro:~/dev-resources/axe-core% npm run api-docs

> axe-core@3.4.0 api-docs /Users/henrick/dev-resources/axe-core
> jsdoc --configure .jsdoc.json

WARNING: The @type tag does not permit a description; the description will be ignored. File: rule-result.js, line: 28
WARNING: The @type tag does not permit a description; the description will be ignored. File: rule-result.js, line: 32
ERROR: Unable to parse a tag's type expression for source file /Users/henrick/dev-resources/axe-core/lib/core/utils/preload-cssom.js in line 121 with tag title "param" and text "{[Array<Array<...>]} assets nested assets (varying depth)": Invalid type expression "[Array<Array<...>]": Expected "!", "$", "'", "(", "*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter, or [1-9] but "[" found.
ERROR: Unable to parse a tag's type expression for source file /Users/henrick/dev-resources/axe-core/lib/core/utils/preload-cssom.js in line 127 with tag title "param" and text "{[Array<Array<...>]} assets nested assets (varying depth)": Invalid type expression "[Array<Array<...>]": Expected "!", "$", "'", "(", "*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter, or [1-9] but "[" found.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! axe-core@3.4.0 api-docs: `jsdoc --configure .jsdoc.json`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the axe-core@3.4.0 api-docs script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/henrick/.npm/_logs/2019-11-22T21_44_44_261Z-debug.log

Here are the contents of the npm debug log:

0 info it worked if it ends with ok
1 verbose cli [
1 verbose cli   '/Users/henrick/.nvm/versions/node/v12.13.1/bin/node',
1 verbose cli   '/Users/henrick/.nvm/versions/node/v12.13.1/bin/npm',
1 verbose cli   'run',
1 verbose cli   'api-docs'
1 verbose cli ]
2 info using npm@6.12.1
3 info using node@v12.13.1
4 verbose run-script [ 'preapi-docs', 'api-docs', 'postapi-docs' ]
5 info lifecycle axe-core@3.4.0~preapi-docs: axe-core@3.4.0
6 info lifecycle axe-core@3.4.0~api-docs: axe-core@3.4.0
7 verbose lifecycle axe-core@3.4.0~api-docs: unsafe-perm in lifecycle true
8 verbose lifecycle axe-core@3.4.0~api-docs: PATH: /Users/henrick/.nvm/versions/node/v12.13.1/lib/node_modules/npm/node_modules/npm-lifecycle/node-gyp-bin:/Users/henrick/dev-resources/axe-core/node_modules/.bin:/Users/henrick/google-cloud-sdk/bin:/Users/henrick/.nvm/versions/node/v12.13.1/bin:/Library/Frameworks/Python.framework/Versions/3.6/bin:/usr/local/git/current/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin
9 verbose lifecycle axe-core@3.4.0~api-docs: CWD: /Users/henrick/dev-resources/axe-core
10 silly lifecycle axe-core@3.4.0~api-docs: Args: [ '-c', 'jsdoc --configure .jsdoc.json' ]
11 silly lifecycle axe-core@3.4.0~api-docs: Returned: code: 1  signal: null
12 info lifecycle axe-core@3.4.0~api-docs: Failed to exec api-docs script
13 verbose stack Error: axe-core@3.4.0 api-docs: `jsdoc --configure .jsdoc.json`
13 verbose stack Exit status 1
13 verbose stack     at EventEmitter.<anonymous> (/Users/henrick/.nvm/versions/node/v12.13.1/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:332:16)
13 verbose stack     at EventEmitter.emit (events.js:210:5)
13 verbose stack     at ChildProcess.<anonymous> (/Users/henrick/.nvm/versions/node/v12.13.1/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
13 verbose stack     at ChildProcess.emit (events.js:210:5)
13 verbose stack     at maybeClose (internal/child_process.js:1021:16)
13 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:283:5)
14 verbose pkgid axe-core@3.4.0
15 verbose cwd /Users/henrick/dev-resources/axe-core
16 verbose Darwin 18.7.0
17 verbose argv "/Users/henrick/.nvm/versions/node/v12.13.1/bin/node" "/Users/henrick/.nvm/versions/node/v12.13.1/bin/npm" "run" "api-docs"
18 verbose node v12.13.1
19 verbose npm  v6.12.1
20 error code ELIFECYCLE
21 error errno 1
22 error axe-core@3.4.0 api-docs: `jsdoc --configure .jsdoc.json`
22 error Exit status 1
23 error Failed at the axe-core@3.4.0 api-docs script.
23 error This is probably not a problem with npm. There is likely additional logging output above.
24 verbose exit [ 1, true ]

[straker]

Thanks for the report. We should also add a test to our CircleCI build that ensures the docs can be built.

[padmavemulapati]

@WilcoFiers and @straker I am not getting into any errors now, able to see the doc/api. Note: The two warnings, which are fine, are still showing up WARNING: The @type tag does not permit a description; the description will be ignored. File: rule-result.js, line: 28 WARNING: The @type tag does not permit a description; the description will be ignored. File: rule-result.js, line: 32