From 8b22e777056a5f7015945c4caa11dd32d19ea306 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 6 Oct 2019 10:15:52 +0800 Subject: [PATCH] feat(`check-tag-names`): allow undocumented jsdoc `modifies` tag and missing closure tags --- .README/rules/check-tag-names.md | 59 +++++++++++++++++++++++++++++- README.md | 59 +++++++++++++++++++++++++++++- src/jsdocUtils.js | 8 ++++- src/tagNames.js | 61 +++++++++++++++++++++++++++----- 4 files changed, 176 insertions(+), 11 deletions(-) diff --git a/.README/rules/check-tag-names.md b/.README/rules/check-tag-names.md index c896ae027..732ce2381 100644 --- a/.README/rules/check-tag-names.md +++ b/.README/rules/check-tag-names.md @@ -47,6 +47,7 @@ memberof memberof! mixes mixin +modifies (Currently undocumented but in source) module name namespace @@ -75,6 +76,62 @@ version yields ``` +The following synonyms are also recognized: + +``` +arg +argument +const +constructor +defaultvalue +desc +emits +exception +extends +fileoverview +func +host +method +overview +prop +return +var +virtual +yield +``` + +For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc) +(or Closure), one may also use the following: + +``` +template +``` + +And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#nosideeffects-modifies-thisarguments), +one may also use: + +``` +define +dict +export +externs +final +implicitCast (casing distinct from that recognized by jsdoc internally) +inheritDoc (casing distinct from that recognized by jsdoc internally) +noalias +nocollapse +nocompile +noinline +nosideeffects +polymer +polymerBehavior +preserve +struct +suppress +template +unrestricted +``` + Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid. #### Options @@ -86,7 +143,7 @@ The format is as follows: ```json { - "definedTags": ["define", "record"] + "definedTags": ["note", "record"] } ``` diff --git a/README.md b/README.md index c133f888a..b958178f0 100644 --- a/README.md +++ b/README.md @@ -1417,6 +1417,7 @@ memberof memberof! mixes mixin +modifies (Currently undocumented but in source) module name namespace @@ -1445,6 +1446,62 @@ version yields ``` +The following synonyms are also recognized: + +``` +arg +argument +const +constructor +defaultvalue +desc +emits +exception +extends +fileoverview +func +host +method +overview +prop +return +var +virtual +yield +``` + +For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc) +(or Closure), one may also use the following: + +``` +template +``` + +And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#nosideeffects-modifies-thisarguments), +one may also use: + +``` +define +dict +export +externs +final +implicitCast (casing distinct from that recognized by jsdoc internally) +inheritDoc (casing distinct from that recognized by jsdoc internally) +noalias +nocollapse +nocompile +noinline +nosideeffects +polymer +polymerBehavior +preserve +struct +suppress +template +unrestricted +``` + Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid. @@ -1458,7 +1515,7 @@ The format is as follows: ```json { - "definedTags": ["define", "record"] + "definedTags": ["note", "record"] } ``` diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js index 64d2255ec..4c507074a 100644 --- a/src/jsdocUtils.js +++ b/src/jsdocUtils.js @@ -1,5 +1,11 @@ import _ from 'lodash'; -import tagNames from './tagNames'; +import {jsdocTags, closureTags} from './tagNames'; + +// Todo: Distinguish closure tags +const tagNames = { + ...closureTags, + ...jsdocTags, +}; const getFunctionParameterNames = (functionNode : Object) : Array => { const getParamName = (param) => { diff --git a/src/tagNames.js b/src/tagNames.js index 055819ac0..dd8cda314 100644 --- a/src/tagNames.js +++ b/src/tagNames.js @@ -1,4 +1,12 @@ -export default { +const jsdocTagsUndocumented = { + // Undocumented but present; see + // https://github.com/jsdoc/jsdoc/issues/1283#issuecomment-516816802 + // https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js#L594 + modifies: [], +}; + +const jsdocTags = { + ...jsdocTagsUndocumented, abstract: [ 'virtual', ], @@ -65,6 +73,7 @@ export default { 'memberof!': [], mixes: [], mixin: [], + module: [], name: [], namespace: [], @@ -90,13 +99,6 @@ export default { static: [], summary: [], - // `@template` is not part of standard jsdoc on https://jsdoc.app but is - // used by Closure per: - // https://github.com/google/closure-compiler/wiki/Generic-Types - // and by TypeScript per: - // https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc - template: [], - this: [], throws: [ 'exception', @@ -111,3 +113,46 @@ export default { 'yield', ], }; + +const TypeScriptTags = { + // `@template` is also in TypeScript per: + // https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc + template: [], +}; + +const closureTags = { + ...TypeScriptTags, + + // From https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler + // These are all recognized in https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js + // except for the experimental `noinline` and the casing differences noted below + + // Defined as a synonym of `const` in jsdoc `definitions.js` + define: [], + + dict: [], + export: [], + externs: [], + final: [], + + // With casing distinct from jsdoc `definitions.js` + implicitCast: [], + + // With casing distinct from jsdoc `definitions.js` + inheritDoc: [], + + noalias: [], + nocollapse: [], + nocompile: [], + noinline: [], + nosideeffects: [], + polymer: [], + polymerBehavior: [], + preserve: [], + struct: [], + suppress: [], + + unrestricted: [], +}; + +export {jsdocTags, closureTags};