Erroneous parsing of decorators in JSDoc code blocks

[nberlette]

When using deno doc --json, example code blocks that contain decorators prove to be problematic for the parser. I'm not sure if this problem persists in --html or in the pretty-printed format in the CLI, but I would assume so since they all use the same parser under the hood AFAIK.

It stems from the @ prefix, which has also been a long running problem with the built-in JSDoc parser used by VSCode's intellisense, and a lot of other projects that incorporate JSDoc comment parsing in their logic. The parser gets confused and thinks the decorator is actually a malformed JSDoc tag, leading to unexpected (and usually terribly formatted) results.

Here's an example from the module doc comment in a JSR package of mine. Note the "unsupported" tags, particularly the last one. You can see it's parsing tags from inside an example code block.

{
  "version": 1,
  "nodes": [
    // ...
    {
      "name": "",
      "location": {
        "filename": "file:///workspaces/decorators/packages/types/mod.ts",
        "line": 1,
        "col": 0,
        "byteIndex": 0
      },
      "declarationKind": "export",
      "jsDoc": {
        "tags": [
          {
            "kind": "module"
          },
          {
            "kind": "unsupported",
            "value": "@log(\"class\") class Example {\n// ...\n"
          },
          {
            "kind": "unsupported",
            "value": "@log(\"method\") method() { return \"foo\" }\n"
          },
          {
            "kind": "unsupported",
            "value": "@log(\"getter\") get field() { return 42 }\n}\n```"
            // ---- the tell-tale sign its in an example code block  ^^^
          }
        ]
      },
      "kind": "moduleDoc"
    }
  ]
}