microsoft / tsdoc

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

eslint-plugin-esdoc not respecting noStandardTags default (false) #424

Open blipk opened 2 weeks ago

blipk commented 2 weeks ago

If I use this tsdoc.json

{
    "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

    "supportForTags": {
        "@fileoverview": true,
        "@name": true
    },

    "tagDefinitions": [
        {
            "tagName": "@fileoverview",
            "syntaxKind": "block",
            "allowMultiple": false
        },
        {
            "tagName": "@name",
            "syntaxKind": "modifier",
            "allowMultiple": false
        }
    ]
}

Then all the standard tags are giving errors: image

Same result if I explicitly set noStandardTags: false

Do I have to add them all to supportForTags? Or is there a reference file I can add to extends?

Neither of those options make sense as tagDefinitions says "Additional tags to support when parsing documentation comments with TSDoc" which implies they're additional to the standard tags.

eslint versions:

{
"@eslint/js": "^9.9.1",
"eslint": "^9.9.1",
"eslint-plugin-tsdoc": "^0.3.0",
"typescript-eslint": "^8.3.0"
}
blipk commented 2 weeks ago

https://github.com/microsoft/tsdoc/issues/298

Similar issue here that confirms what I thought - MS are too lazy to properly document or support their own tools.

Thanksfully there aren't too many tags and I added them here if anyone else comes across this issue:

    "extends": ["./node_modules/typedoc/tsdoc.json"],
    "supportForTags": {
        // Indicate that the custom tag is supported by your tooling.  (Without this, warnings may
        // be reported saying that the tag is unsupported.)
        "@fileoverview": true,
        "@name": true,

        // Indicate that the default tags are supported: https://github.com/microsoft/tsdoc/issues/424
        "@alpha": true,
        "@beta": true,
        "@decorator": true,
        "@deprecated": true,
        "@defaultValue": true,
        "@eventProperty": true,
        "@example": true,
        "@experimental": true,
        "@inheritDoc": true,
        "@internal": true,
        "@label": true,
        "@link": true,
        "@override": true,
        "@packageDocumentation": true,
        "@param": true,
        "@privateRemarks": true,
        "@public": true,
        "@readonly": true,
        "@remarks": true,
        "@returns": true,
        "@sealed": true,
        "@see": true,
        "@throws": true,
        "@typeParam": true,
        "@virtual": true,

        // TypeDoc
        "@category": true,
        "@categoryDescription": true,
        "@document": true,
        "@enum": true,
        "@event": true,
        "@group": true,
        "@groupDescription": true,
        "@hidden": true,
        "@hideconstructor": true,
        "@ignore": true,
        "@interface": true,
        "@module": true,
        "@namespace": true,
        "@overload": true,
        "@private": true,
        "@property": true,
        "@protected": true,
        "@satisfies": true,
        "@template": true,
    },