DEV Community

loading...

Discussion on: 💻 Documentation as code

Collapse
adamcoster profile image
Adam Coster Author

Ooooh, that's neat! The trick there would be finding such a system that has full support in the IDE (intellisense, linting, etc). I'll have to poke around for JavaScript/Typescript equivalents.

Collapse
stereoplegic profile image
Mike Bybee • Edited

Uh, JSDoc? One setting in VS Code for Intellisense (enable for JavaScript), one ESLint plugin (eslint-plugin-jsdoc), and you no longer need TS for static type checking. You can (and probably should) document examples too.

Actually install jsdoc as a dev dependency (which isn't required for the above paragraph, instead just requiring JSDoc comment syntax), and you get a generator for code docs.

Thread Thread
adamcoster profile image
Adam Coster Author

JSDoc is great, and gets at a subset of the general problem.

JSDoc doesn't cover all the functionality that Typescript does for type information, and is quite verbose in comparison. Using both allows Typescript to handle types and JSDoc to handle non-code metadata (explanations, samples), which can all be pulled together with TypeDoc and similar tools.

Thread Thread
stereoplegic profile image
Mike Bybee

True. You have to write fewer types just for the sake of other types.

Thread Thread
berkmann18 profile image
Maximilian Berkmann

JSDoc is nice until you want to generate the documentation where you then feel like you're using an unmaintained tool; documentation.js is a good alternative although TS removes the need for verbosity and the other pros it gives.