RFC: IntelliSense completion for custom TSDoc tags

[octogonz]

@evanargelion has been asking about defining custom TSDoc tags for toolchain directives. A build task would use the compiler API to extract the comments, invoke the TSDoc parser, and then use this information to affect the build output. For example:

/**
 * @clientCallable(excludedFromRest = true)
 * @apiSet(version = PolyfillableDownTo1_1, IntroducedInVersion = 1.3)
 */
export class BindingSelectionChangedEventArgs {
  . . .
}

He'd like for IntelliSense to help developers write these tags correctly, but without having to implement a custom VS Code extension.

One idea would be to rely on the compiler type system, e.g. define clientCallable and apiSet as a TypeScript interface (similar to how JavaScript decorators or .NET attributes work). However in TypeScript that would probably require the definitions to be imported into the TypeScript source file. It also means the IntelliSense requires a compiler analysis and source code that compilers (maybe as a separate NPM package that would be a dev dependency?).

Another idea would be to define a simpler data file where these definitions can be found, something like a JSON schema. This has the advantage that TSDoc itself could validate these schemas while remaining decoupled from the TypeScript compiler.

Is this an important developer scenario for anyone else? How would you design it?

[octogonz]

@DanielRosenwasser

[DanielRosenwasser]

This is interesting, but I guess the question is how do you encode this in a generalized and pluggable manner? Additionally, do you end up having to import types to use JSDoc? @rbuckton and @sandersn might have some thoughts here.

[sandersn]

@DanielRosenwasser could a TS plugin do this? It’s been over a year since I used that API, but I think it has the ability to hook the completion requests and provide its own completions in arbitrary locations. Doesn’t angular do basically this?

[octogonz]

Alternatively, if we wanted to follow the model of JSON schemas, it might go like this:

In your package.json file, you would register a custom TSDoc schema:

{
  "name": "my-project",
  "version": "1.0.0",
  "tsdoc": {
    "tagSchemas": [
      "https://some-website.com/tsdoc-schemas/my-doc-tool/my-custom-tags.tsdoc.json"
    ]
  },
  "license": "MIT",
  "devDependencies": {
    "my-doc-tool": "~1.0.0"
  }
}

Then VS Code IntelliSense would fetch the JSON file from the web server. There would be some kind of schema definition, maybe something like this:

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

  "inlineTagDefinitions": [
    {
      "tagName": "@clientCallable",
      "parameters": [
        {
          "parameterName": "excludedFromRest",
          "type": "boolean",
          "required": true
        }
      ]
    }
  ]
}

If we want the TSDoc parser to support this, it doesn't need to depend on the web server. Instead, maybe it could discover the schema on disk by looking for a custom field in the node_modules/my-doc-tool/package.json file.