Typedoc: TypeDoc@future

[Gerrit0]

This is a tracking issue for where I'm trying to take TypeDoc. Nothing is set in stone, but the "closer to now" issues are less likely to change than those several versions out.

v0.20 - Well behaved documentation generation - "Library Mode" - released 12/28/20

This is being released December 28th, 2020. See #1364 for a detailed tracking thread.

Motivation...

TypeDoc currently has two modes - file and modules. Both of these modes rely on traversing the AST of a given program to figure out what should be documented. This mostly works but has some shortcomings.

1. Re-exports are handled poorly (and before 0.17 weren't handled at all!)
2. Documentation becomes heavily nested (in modules mode), making it harder to find what you are looking for.

The way a documentation generator should work is by using the compiler API to ask what is exported, and then documenting that. TypeDoc. Originally, this was going to be added as a third "mode" to TypeDoc, however, a proper implementation demanded that the converters work in a fundamentally different way... Since I lack the time to maintain both implementations in sync, library mode will replace both file and modules mode. Since rewriting the converters resulted in changing the models, this broke the themes... so this turned into almost a full rewrite. See #1364 for a tracking thread for what's being done and still needs to be done for this to be complete.

Note that there is an implementation of library mode already in #1184. This makes incredibly minimal changes. While it works for many simple cases, it has major problems. If you want to use it, you can install version 0.17.0-3.

v0.21 - Output cleanup

TypeDoc's themes have been limped along for quite a while. Today they use Handlebars for templating and rely on several magical plugins to massage their output into a reasonable state. It all works, but is difficult to extend. Most third party themes are built in a way that updates to TypeDoc's output that should not necessarily break the theme will. This is partially the result of poor documentation, and partially that nobody fully understands how the themes work.

This update won't be groundbreaking in terms of features, but it should provide nice user experience improvements:

• Builtin support for dark mode
• Smaller typedoc install size
• Easier theme development via templating that uses TS language features

vEventually - TSDoc standard

TypeDoc currently doesn't conform to the TSDoc standard (https://github.com/microsoft/tsdoc)

This is fine, TypeDoc existed for 4 years before TSDoc did... but it would be nice use it for consistency with other documentation tools. I haven't given this too much thought yet. It might need to be pushed out further depending on what I discover while working on library mode.

[Bnaya]

The future is very exciting for sure! :)

[christopherthielen]

Do we care?

I have authored a few plugins and I don't care if it's a breaking change (if it means we get library mode).

I'm using the node in my plugins (1 2) to get the raw comment. I think this was a carryover necessary in an early version of typedoc. I doubt my plugins actually need the AST node with recent versions of typedoc.

[jun-sheaf]

@Gerrit0 Could we perhaps add more distribution tags? Currently there is no beta tag but we have beta features such as library mode. We could even branch the tags out like so:

17.8.0 -> @beta -> @library

to help separate some concerns.

[Gerrit0]

There is an @next tag, which targets library mode currently, I do like renaming that to @beta... I'll leave @next as an alias for now to avoid breaking people who use it, but won't use it for future releases. (Done!)

I'm not sure about adding @library, particularly because the currently published beta for it is a dead end.

[jun-sheaf]

Well, the idea behind the ‘library’ tag was for the current ‘next’ tag. ‘beta’ should be a completely new tag for which ‘library’ would be branched off from (as opposed to branching off the current main). In short, beta features should be branching off the ‘beta’ tag (if any such features really do require their own tag, e.g. library mode).

[benmccann]

It's very exciting that 0.20 has been released! I was curious whether adding back support for JSDoc might be somewhere on the roadmap? (JSDoc support being dropped was mentioned in https://github.com/TypeStrong/typedoc/issues/1209#issuecomment-733931116)

[NaridaL]

@Gerrit0 Thanks for all the hard work, this looks very promising 👍 🎉

[Gerrit0]

JS support - I'm certainly open to a PR which implements this. I don't want to schedule it ahead of features for TypeScript users, however (especially since there's a workaround - TS can generate declaration files, which can then be consumed by TypeDoc). #1214 would be the place to watch for progress there. Looking at the TypeScript docs for those tags indicates that there are probably quite a few edge cases.

A comprehensive-ish set of tests for typedef/callback would make implementing this a lot easier from my point of view. It looks like there are a few possible forms.

(It isn't entirely accurate to say that we dropped JSDoc support - we never had it, TypeDoc just happened to ignore it)