Support literal enum of strings

[ngryman]

Hey,

Would you consider supporting @param enum of strings like those in this proposal: jsdoc/jsdoc#629.

Thanks!

[tmcw]

Yep, we already support the examples given that issue, with the exception that

/**
 * @param {MediaType} mediaType - Type of the media
 */
function foo(mediaType){};
/**
 * @type {('MP4'|'WEBM')} MediaType - Allowed media types
 */

Should have @typedef instead of @type for the custom type definition (@type is used to declare the type of an attached value, rather than a type definition.

Feel free to file an issue if you see the existing support lacking in any way!

[ngryman]

Thanks for your answer.

I should have elaborated a bit more. I'm talking about literal, in-place or anonymous enums without any reference to existing type. I don't know the name for this 🤣. But I know that some other tools support it. It's really convenient for simple one place enums.

This currently crashes:

/**
 * @param {('pre'|'post')} [order='pre'] Traversal mode
 * or
 * @param {'pre'|'post'} [order='pre'] Traversal mode
 */

Output

> documentation build lib/*.js --format md --output docs/api.md

/Users/ngryman/Projects/arbre/node_modules/documentation/lib/commands/build.js:67
      throw err;
      ^

Error: Unknown type StringLiteralType
    at formatType (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/util/format_type.js:174:11)
    at commaList (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/util/format_type.js:60:22)
    at formatType (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/util/format_type.js:125:12)
    at formatType (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/util/format_type.js:166:30)
    at /Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/markdown_ast.js:48:41
    at Array.map (native)
    at paramList (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/markdown_ast.js:43:51)
    at paramSection (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/markdown_ast.js:66:9)
    at generate (/Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/markdown_ast.js:175:13)
    at /Users/ngryman/Projects/arbre/node_modules/documentation/lib/output/markdown_ast.js:194:26

This works by misinterpreting pre and post as types:

/**
 * @param {pre|post} [order='pre'] Traversal mode
 */

EDIT: I edited the title to try to be more precise.

[tmcw]

What version of documentation.js are you using? That input also works for me, and we've supported StringLiteralType since v4.0.0-beta.18

[ngryman]

I'm using 4.0.0-beta.18. Here is the offending repo for more informations: https://github.com/arbrejs/arbre.

[tmcw]

Should that repository fail on npm run docs? I've tried that, and it works properly:

~/src〉g clone https://github.com/arbrejs/arbre.git
Cloning into 'arbre'...
remote: Counting objects: 107, done.
remote: Total 107 (delta 0), reused 0 (delta 0), pack-reused 107
Receiving objects: 100% (107/107), 76.08 KiB | 0 bytes/s, done.
Resolving deltas: 100% (13/13), done.
~/src〉cd arbre
~/src/arbre〉yarn
yarn install v0.17.9
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 📃  Building fresh packages...
$ npm run build -s
'default' is not exported by node_modules/tree-morph/index.cjs
✨  Done in 21.67s.
~/src/arbre〉npm run docs

> arbre@0.0.0 docs /Users/tmcw/src/arbre
> documentation build lib/*.js --format md --output docs/api.md

[ngryman]

Yes sorry I didn't push the crashing jsdoc code. I've pushed it in the documentation-bug branch if you want.
Basically you can just quote {pre|post} values in lib/walk.js so documentation parses it as strings not types.

[tmcw]

✨ I can confirm that the issue is present in documentation.js < beta.18 and fixed in beta.18 and beyond.

Partly this is due to semver, unfortunately: specifying ^4.0.0-beta.18 gets 4.0.0-beta9. I'm going to get out of this mess ASAP and just release 4.0.0.

Going to write a testcase for this problem and close with that PR.