microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.67k stars 131 forks source link

How to ignore arguments to non-standard tags? #337

Open crystalfp opened 1 year ago

crystalfp commented 1 year ago

I'm using tsdoc and its eslint plugin with great satisfaction. Now, to document *.vue files (compose API + script setup + typescript + vite), I started using vue-docgen-cli (I had problems installing vue-styleguidist). This tool, to document emits, uses a non standard tag @arg with a complex argument. Here is an example:

const emit = defineEmits([
  /**
   * Changed when the dialog visibility changes
   * @arg {boolean} visibility - Dialog is visible
   */
  "update:modelValue"
]);

Rightly eslint complains about the braces:

tsdoc-malformed-inline-tag: Expecting a TSDoc tag starting with "{@"
tsdoc-escape-right-brace: The "}" character should be escaped using a backslash to avoid
    confusion with a TSDoc inline tag

Tsdoc.json is (simplified):

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
     "tagDefinitions": [
        {
            "tagName": "@arg",
            "syntaxKind": "block"
        }
    ],
    "supportForTags": {
        "@arg": true
    }
}

Changing braces or escaping them makes the argument not recognized by vue-docgen. Is there a way to make tsdoc ignore or not check a block tag? Or the only way is to complain with vue-docgen developers? Thanks for enlighten me! mario

crystalfp commented 1 year ago

Well, the solution is to disable the rule around this comment. Not nice, in my opinion, but solved the problem.