document VT features in docstrings

[jerch]

PR to document VT features inline in docstrings.

@Tyriar Was not able to get this working with typedoc, it does not work with our repo/project structure (throws tons of errors). Thus I parse the comments myself in bin/extract_vtfeatures.js.

Currently it respects the following notations:

• single line only with basic data

// @vt: <status> <kind> <mnemonic> <"name"> "<sequence>" "<short description>"

• multiline with optional long description

/**
 * ...
 * @vt: <status> <kind> <mnemonic> "<name>" "<sequence>" "<short description>"
 * Some longer description for this goes here until next empty line...
 *
 * ...
 */

You can either run the command with node bin/extract_vtfeatures.js src/**/*.ts or as yarn run --silent vtfeatures which outputs a markdown document with tables of the features.

Next steps:

• integrate this somehow into the wiki/webpage, maybe rebuild those with every release
• document all existing features in InputHandler
• respect long descriptions in output to further document special cases

[jerch]

Created a stub wiki page with the output: https://github.com/xtermjs/xterm.js/wiki/VT-features

[jerch]

@Tyriar I think the feature descriptions are better moved to the function declarations instead of the registering step. This would save some duplicated descriptions. Have to update the "parser" for this (currently does not support multiple @vt sections in multiline comments).

[jerch]

Writing @vt: docstrings has now the following parsing rules:

• a vt feature is declared by a @vt: token at the start of a comment line (only TS files are scanned)
• first line denotes the content of the main tables in this form:

// @vt: <status> <kind> <mnemonic> "<name>" "<sequence>" "<short description>"

• follow up lines are used as long description
• long description ends after 2 empty lines, a new @vt: token or at the end of a multiline doc string
• long description can contain markdown syntax supported by kramdown (jekyll)
• For status there are some macros defined. These can be used in the status field of the single line, or anywhere in the long description.
  • #Y: supported
  • #N: unsupported
  • #P[some reason]: partial support with reason in title
  • #B[some reason]: broken support with reason in title

[jerch]

@Tyriar The basic stuff is done. Not sure yet where the automatic build script should end up. As far as I see, the API doc updates are scripted in xtermjs.org repo, imho it would work likewise for the vtfeatures. Once this has landed, a build script in the website repo could do something like this:

git clone https://github.com/xtermjs/xterm.js.git
cd xterm.js
yarn
yarn run --silent vtfeatures > target_file_in_website_repo.md

Then just build the created markdown file along with others in the website project.

Up for review.

[Tyriar]

Created a follow up xtermjs/xtermjs.org#118