Version 0.20 tracking

[Gerrit0]

This issue tracks the work being done on the next feature release of TypeDoc. I will be posting a weekly update here covering what I've done this week, as well as what's next to be done.

You can try out a beta of 0.20 by installing typedoc@beta with npm i typedoc@beta.

---

Originally, this release was slated to be version 1.0, it contained a major rewrite which fixed most to all of the issues I have with the current implementation of TypeDoc. However, I've since realized that this was a bad idea - I broke too many things, so "library mode" will be releasing as 0.20 before the end of the year.

Old text

This issue tracks the work being done on version 1.0. I will be posting a weekly update here covering what I've done this week, any new problems discovered, and updating the checklist in this post with what's been completed. The checklist in this post was originally taken from this post in the original PR, without including any of the already completed items.

If you are interested in looking at the work in progress package, you can install typedoc@dev, which will be published whenever a change in version is pushed to the library-mode branch.

At the current rate that I'm getting things done, it's looking like this won't be ready until November/December... I was really hoping for sooner, but can't devote every weekend to this, though I try to do at least one task per week ;)

Tasks

TypeDoc proper

• Finish ObjectReflection converter (medium)
• Fix converter for destructured outputs (small)
• Add indexed signatures to models that can have them. I forgot they existed when rebuilding the models... (medium)
• Detect and convert static class members (smallish)
• Update plugins that were broken when rebuilding converters
  • Decorator plugin (medium)
  • Implements plugin (medium)
  • Deep comment plugin (small, probably merge with the existing comment plugin)
• Test on a bunch of different projects, particularly large ones. (Apache Arrow, Jupyterlab) (??? depends on what issues are found)
• (done) Review existing options to see which ones still make sense. (medium)
• Update variable converter to possibly convert variables as functions (smallish) (Function exported as variable despite @function tag #858, but without requiring @function, Variables of kind ConditionalExpression have defaultValue set to condition #401, )
• Sort order option (Beyond alphabetic ordering or methods and properties #112), see src/lib/plugins/sort.ts

Comments

• Make @category work again (medium)
• Fix {@link} and [[link]] (medium)
• Make @inheritdoc work (small/medium)

Themes

• Support hideGenerator flag (smallish, need to allow templates access to application.options)
• (done) Make overriding templates easy for users (small/medium)
• (done) Write docs on how to create a custom theme (medium, I want to do this right, not just the minimal page we currently have, particularly important because 1.0 breaks existing themes)
• Talk with the people that built the markdown plugin about how to integrate (medium)
• Make search work (medium)
• Make sure mobile experience is decent (medium)
• (done) Make light/dark code themes configurable (small)
• Add icons for reflection types (medium)

Plugins / Developer Docs

• Take a look at existing plugins to see what events they use, if the existing emitted events meet those needs, or if we need other events. (medium)
• Write "how to build a TypeDoc plugin" (medium)
• Update the development page on the website (medium)
• Figure out what should be exported, and export only those symbols

Extra (nice to have, but won't block a release)

• Highlight headings according to the color scheme chosen by users, not just code snippets (medium? Tricky. I spent a few hours on it, failed)
• Add a reflection for "union enums" RFC: Specify that doc comments are allowed on simple union types microsoft/tsdoc#164
• Update models to make type parameters have a reflection - Support making type parameters private #1319.
• Recognize global objects and combine them all into a single special module,
• Figure out how @event ought to work. The old way of handling it flat won't work anymore... and it isn't particularly clear how it should be used.
• Create a second theme

Future (almost certainly not in 1.0, but I'm thinking about it)

• JSON deserialization (Json deserialization #910)
• Support for /// comments Triple-slash comments for JSDoc microsoft/TypeScript#39930

Help out

There's still quite a bit to be done. Help on any of the uncompleted items above is greatly appreciated. I could especially use some help on making the default theme better - frontend dev is not my specialty. If you are having trouble, feel free to reach out by making an issue for the task you're working on, through the TypeScript Discord, or through the TypeDoc Gitter.

[bennypowers]

@Gerrit0 I'm happy to help with light/dark theme for typedoc, based on css custom properties and prefers-color-scheme. Maybe using this: https://github.com/GoogleChromeLabs/dark-mode-toggle

[Gerrit0]

Thanks @bennypowers! We've chatted about this a bit on Discord.

---

What's been done this week is published as typedoc@1.0.0-dev.3.

Maintenance

• Since the currently released version of TypeDoc still needs to be maintained, it is in my best interest to avoid spending more time on it. (and therefore less time working on this!). This week I added automatic publishing to typedoc-default-themes when the version number is updated - it still isn't fully automatic, it doesn't create a tag + a release page, but it saves some time.
• Upgraded dependencies for the themes, resolving some security vulnerabilities in devDependencies + removed lunr from dependencies - it was only ever used in bundling... which happens before publish.

Development

• This week I spent most of my time figuring out how themes ought to work and writing some documentation for how they will. You can preview the docs here. (The examples will complain because not everything is exported yet... see work added)
• PropertyReflection didn't have a isReadonly property, now corrected + properly initialized
• I also did some experimentation with performance - 20x slowdown compared to 0.11.x #975 has a test case where TypeDoc performs incredibly slowly, taking several minutes to run. This rebuilt version of TypeDoc converts the same declaration file in under 5 seconds on my machine. I was still curious if we could do better, so I did some performance measurements... and the short answer is... not really. TypeDoc code only took up ~5% of that runtime. TypeScript took ~50%, Shiki (highlighting) took another 35%, loading modules 5%, and ~5% unaccounted for (gc?). Exporting JSON only took 2 seconds.
• Originally, I wasn't planning on supporting files which were not modules, but while testing performance, I realized that it wasn't very difficult to support global files which contain an exported namespace of the same name as the file (as the monaco.d.ts file there.
• I wasn't originally planning on working on themes this week... I got roped into that while looking into which options still made sense. Quite a few didn't. includeDeclarations (just works now if you specify a declaration file as an entry point) excludeNotExported (we only consider exported values now), listInvalidSymbolLinks (this should always be on), externalPattern (this was one of several ways to try to exclude values, shouldn't be necessary anymore, everyone uses modules)

Work added

• I realized after writing docs on how themes work, that there wasn't a task for figuring out what should be exported, and exporting only those members... which definitely needs to happen before 1.0. This will need to wait until much closer to release, or I would have done it now.

[Gerrit0]

Fairly small update this week, I didn't have much time to work on TypeDoc.

Maintenance

• https://typedoc.org now has syntax highlighting in code blocks thanks to @sidthesloth92
• The default theme colors are now WCAG AA contrast compliant thanks to @chadlavi - reinstalling without a lockfile will pick up the update.
• Fixed export declarations within namespaces (Re-exported symbols inside a namespace are ignored #1366)
• Since I keep spending at least a couple hours in the old code each week... it seemed worth it to upgrade dependencies. I got rid of the deprecated TSLint for ESLint + Prettier (Migrate to ESLint #1190).

Development

• I started making {@link} work, but didn't have time to finish it. This is what I'll be starting with next weekend.

[Gerrit0]

My apologies for a lack of an update last week - I went out with some friends and didn't handle the junk food well...

This week was also fairly unproductive... but at least I did one thing! Work has been very busy, not much brain left over for the weekend. Particularly for the rather tricky task of making comment parsing better. While working on {@link}, I realized there were several issues with the existing implementation which would cause problems with the later comment parsing/rendering work... so I set out to remedy that.

Development

• Light/dark themes are now configurable
• Started working on converting variables as functions... which opened up some questions about what I'm actually doing with this "rewrite"... I need to spend some time next weekend figuring out if I can skip the rewrite. Now that I know more about library mode, I'm not fully convinced it is necessary. There are parts that I still want to change, but this rewrite is really something different than TypeDoc.

[Gerrit0]

This weekend I spent trying to avoid the rewrite. I haven't succeeded yet, but I made some good strides, I believe it is possible to (mostly) use the existing architecture and avoid spending a bunch of time rebuilding code that works today. Toward that end, I ripped out a few options:

• ignoreCompilerErrors - This was a bad idea in the first place. If there are compiler errors, we're asking for a crash later on...
• mode - File mode was a hacky way of avoiding a ton of modules when using "modules" mode. "modules" mode is a specific case of library mode.
• Support for specifying compiler options directly - Restricting this so that compiler options are always read from a tsconfig.json file ensures that we have the same behavior as tsc.

I mostly have library mode working, but am still dealing with some issues where we sometimes need to create references, and sometimes not.... I suspect I'll have a working prototype next week.

[Manish3323]

in our typescript library repo, we are experimenting with typedoc to generate api documentation.
as typedoc@next, i could do mode="library", which i am guessing is a best mode for us as its a web library.
we have both .ts and .tsx files that exposes modules and react-components to our users.
when i do :
mode="library", .tsx files are ignored.
mode="modules" those are parsed and .tsx components are documented.

note : i'm not sure whether it's a bug or not.

my current ts config

"compilerOptions":{
"jsx": "react",
... other ts config's
...
"typedocOptions": {
    "inputFiles": [
      "src/clients",
      "src/components",
      "src/models"
    ],
    "mode": "modules",
    "out": "../docs/ts-docs",
    "exclude": [
      "**/*+(**Impl|**PostCommand|**WsCommand|**index).ts",
      "**/decoders/*",
      "**/*+(**Utils).ts"
    ],
    "jsx": "react",
    "excludePrivate": true,
    "plugin" : "typedoc-plugin-external-module-map",
    "external-modulemap" : ".*\/(clients|components|models)\/",
    "categorizeByGroup": true,
    "categoryOrder": [
      "Services",
      "Agent-Service",
      "Others"
    ]
  }
}