DEV Community

Discussion on: 💻 Documentation as code

Collapse
hassan_schroeder profile image
Hassan Schroeder

Expressive tests make excellent documentation that by definition can't get out of sync with the actual code, regardless of language.

And Elixir, for instance, lets you document each function with code examples that get run along with your unit tests, so that explicit documentation stays in sync with the function code. (See elixir-lang.org/getting-started/mi...)

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.