Feature summary (what you would like to be able to do and where):
Be able to use string literals in type definitions in the JSDoc WMF theme, e.g.
/** * @typedef {Object} Foo * @property {'bar'|'baz'} prop */ /** * @param {'a'|'b'} param * @return {'foo'|Foo|null} */ function fun(param) {}
(TypeScript’s JSDoc parser already supports them.)
Use case(s) (list the steps that you performed to discover that problem, and describe the actual underlying problem which you want to solve. Do not describe only a solution):
Cases in which a value is chosen from a set of strings, and any other strings are invalid, for example:
- The first parameter of $.fn.textSelection() should be one of the values described in prose. It shouldn’t be, for example, 'getContent'.
- mw.loader.getState() returns one of the documented values, never 'failed' or 'unregistered'.
- jQuery.client.Profile contains a lot of fields that may be a useful value or 'unknown', see https://gerrit.wikimedia.org/r/c/jquery-client/+/1014609/comment/97163e70_74679917/.
Benefits (why should this be implemented?):
- They make the developer intent clearer.
- When paired with type check powered by TypeScript, they allow the type checker to flag typos.
Implementation details:
Some keyword literals and literal-like global objects are already recognized by our JSDoc theme, see rJWTH publish.js:22 (at 23b42f16925f342ee43993ed44e26dc2204d85a9). That regex could be expanded to include string literals as well (/^'[^']*'$/).