TSDoc + TypeDoc

Today left me feeling pretty sure everybody else knows some stuff I don’t.

It all started with the @category tag. See, I want to use it with TypeDoc to generate sidebar navigation categories in API documentation pages like this one. Which is awesome, by the way, and built into my Typescript NPM Package Template.

And it’s also less of a shameless plug than it sounds, because (a) I use that template a LOT, and (b) the freaking @category tag was throwing a linting error. Like, everywhere.

TL/DR: Add this file to your package root to get eslint-plugin-tsdoc to support TypeDoc right out of the box!

The source of the error was eslint-plugin-tsdoc, which stinks becuse that ESLint plugin has exactly ONE rule. So it’s either on or off. And I really want to lint my TSDoc comments. But TypeDoc defines a few extra tags—like @category—that eslint-plugin-tsdoc doesn’t know about. So I was stuck.

Google was no help at all.

So I logged onto ChatGPT, and before long I’d talked myself into writing a wrapper around eslint-plugin-tsdoc to catch & ignore errors on valid TypeDoc tags. And, you know, in GPT-land ANYTHING is possible!

That ate up a couple of hours. Let’s just say I’m not proud of it.

Then I thought I’d just fork eslint-plugin-tsdoc and add the extra tags myself. And THAT was when I finally discovered @microsoft/tsdoc-config, a library that loads custom TSDoc configs from a tsdoc.json file. Which, it turns out, is a dependency of eslint-plugin-tsdoc.

Translation: if you’re using eslint-plugin-tsdoc, it is ALREADY looking for a tsdoc.json defining custom tags!

And when I went back to the TypeDoc repo, what do you think I found? Oh yah: a big fat tsdoc.json, all loaded up with custom TypeDoc tags. Including @category.

So I copied that tsdoc.json into my project, and the @category linting error went away. Ditto for my template.

Maybe Google will be kinder to the next guy.