v0.23 Beta Release

It’s several months later than I really wanted to start this process, but 0.23 is finally nearing completion and is ready for beta release! Please try it out and leave feedback either in comments in this issue, or as new issues.

npm install --save-dev typedoc@beta

This release includes two major efforts. A re-imagined default theme thanks to @futurGH, and a complete revamp of TypeDoc’s comment parsing to allow TypeDoc to be compatible with TSDoc.

Theme Rebuild

TypeDoc’s current default theme has remained essentially the same for the past 6 years. It worked, but wasn’t particularly mobile friendly, with small click targets being clustered together. The new theme resolves this, and also makes better use of large screens.

Before	After

TSDoc Compatibility

In 0.22 and earlier, TypeDoc’s comment parser is essentially a line-by-line loop with some regular expressions applied. This does an admirable job of handling most comments, but it is less than ideal when dealing with complicated references. Replacing this with a real parser means that it is possible for TypeDoc to perform much more rigorous validation of comments and distinguish between block/modifier tags.

It is important to note that TypeDoc, while aiming to be compatible with TSDoc, does not require its use. It also does not restrict rendering to TSDoc supported constructs. Comments continue to be rendered via Marked, which means that if Marked supports a feature, TypeDoc generally does too. This is important because many commonly used markdown features are not yet specified by TSDoc (including support for headings, tsdoc/197 and lists tsdoc/178). If this “laxness” isn’t acceptable for your use case, I recommend api-extractor.

Important Breaking Changes

• Support for Node 12 dropped - it will be EOL by the time 0.23 releases for real.
• Support for TS < 4.6 dropped
• @inheritDoc now follows the TSDoc specification when copying documentation.
• Support for [[target]] links has been deprecated. Since TypeScript 4.3, the {@link} syntax will be recognized by editors and used to actually create links, and it should be used instead. v0.24 will remove TypeDoc’s support for [[target]] links.
• Step four in TypeDoc’s link resolution has been removed, which may break some links.
• Comments on export declarations will now only override comments for references and namespaces.
• All top level reflections will now be rendered in their own page. This is more consistent with several other documentation systems and makes exported functions/variables/type aliases no longer feel “tacked on” as is evident with the old system.

New Features

• Added support for the @group tag to override the default grouping by kind (classes, functions, etc.)
• Improved support for several JSDoc style constructs, including detecting @example tags which expect to be treated as code blocks. TypeDoc now matches VSCode’s behavior.
• Members marked with @deprecated will now be rendered with a line through their name.
• If parts of a comment will be overwritten by an @inheritDoc tag, TypeDoc will now warn you about it instead of silently overwriting a comment.

Remaining Work

For additional information about resolved bugs and remaining work to be completed before release, see the changelog.

• Update documentation on https://typedoc.org, add a page/section for each special tag recognized by TypeDoc.
• Restore support for {@link} and [[link]] tags in readme files
• Make comment parser options configurable
• Read tsdoc.json for comment parser configuration
• Full support for declaration references (TypeDoc still just splits link targets on . to try to resolve links), #262, #488, #1326, #1845.
• Add support for additional comment styles, #1433
• Add custom rendering for @see tags
• Show toggles for modifier tags and make default visibility features configurable, #1816.

Future work originally considered for this release

• Add support for a @copyDoc inline tag which can be used to pull pieces of documentation from other entries without fully overriding the comment (@inheritDoc is specified by TSDoc to specifically disallow this, so a new tag), #304
• Experiment with a --commentDiscovery option to tell TypeDoc to delegate all comment discovery to TypeScript

[Gerrit0]

0.23 for real is out! 🎉

[Gerrit0]

It turns out “full support for declaration references” is quite the rabbit hole… TSDoc initially went with one syntax, the maintainers there are looking at switching to a different (much nicer, and similar to JSDoc) syntax, JSDoc uses a third, VSCode handles things similar-ish to how TypeDoc does it today…

My current plan is for TypeDoc to support the beta syntax that TSDoc does, and fall back to matching like it does today if link resolution fails… life is really busy right now though. I wanted to be at a full release or nearly there by now, but it looks like this won’t be fully ready until mid June.