Skip to content

feat: support TSDoc in the doc checks and stubs - #35

Open
botandbang wants to merge 1 commit into
mainfrom
bnb/tsdoc
Open

botandbang wants to merge 1 commit into
mainfrom
bnb/tsdoc

Conversation

@botandbang

Copy link
Copy Markdown
Contributor

This adds TSDoc support to the doc checks and to the stubs that --fix and the language server write. It doesn't validate TSDoc grammar or read tsdoc.json.

Added:

  • A syntax key ("jsdoc" by default, or "tsdoc"), registered as its own feature file. With "tsdoc", stubs write @typeParam T -, @param x - and @packageDocumentation in place of @template T, @param x and @file, require-template asks for @typeParam in its findings, and valid-link reads the A in {@link A#b} as a package name and doesn't look it up. With "jsdoc", A is still a class the file has to declare. The key is in the regenerated docov.schema.json, the README and --print-config, and the cache stamps by it.
  • A TSDoc-style fixture (tests/fixtures/tsdoc/parser.ts) that passes every doc check at error with "syntax": "tsdoc", plus unit tests and Hegel properties for each change below.

Changed:

  • require-template counts @typeParam T - desc and @typeParam T as naming T.
  • empty-tag-description also checks @typeParam, and ignores the - TSDoc puts between a name and its description, so @param x - has no description. A - with no space after it, as in -1, stays part of the text.
  • An inline {@inheritDoc} or {@inheritDoc Ref} in a block's description or any tag's text now means the item inherits its docs, the same as the @inheritdoc block tag, unless it's escaped or inside a code span. One helper decides this for both coverage and the checks that leave inheriting blocks alone, and the escape and code-span test is shared with valid-link.
  • summary-sentence leaves a block that inherits its docs alone. Before this, /** {@inheritDoc Base.m} */ was reported as a summary without a period.
  • valid-link gives no findings for {@link Foo.bar | text}, {@link @scope/pkg#Foo}, {@link (Foo:constructor)} and {@link Foo.(bar:static)} in either syntax, and none for {@link pkg#Foo.bar} with "syntax": "tsdoc".
  • The inherit key's docs and schema mention the inline form.

Removed:

  • Nothing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant