Let’s talk about the state of auto-generated documentation tools for JavaScript

Home / Developer Tools / Let’s talk about the state of auto-generated documentation tools for JavaScript
Let’s talk about the state of auto-generated documentation tools for JavaScript

After I finish hand writing almost a thousand lines of documentation, I vowed to never do that again. So I set out on a quest to find all the best tools to do this tedious task for me.

Surely these tools must already exist, right? npm install something, run a command, and done, right? Maybe not…

I am attempting to document Functional JavaScript code, which is apparently more complicated than it should to be. With the rise of functional javascript, I find it surprising that this is so complicated.

I just want to create docs for something like this:

// how do I document you, little function?
const add = x => y => x + y

I would like VSCODE’s intellisense to understand the docs and I would also like to generate either a Markdown file or HTML.

JSDoc 3

The obvious first start is JSDoc. I believe they are leading this space. But for a site about documentation, their own documentation is really horrifying. I find no information on how to properly document my add function.

I find an open issue Support for curried functions and check the date. October 2016.

rage face

Okay… RIP JSDoc.

Minami

Minami screenshot

This is exactly what I am looking for. The screenshot looks great and… uh oh. JSDoc 3. And the project was last updated in Apr 18, 2017.

RIP Minami.

doxdox

doxdox screenshot

This looks solid. Last commit Feb 19, 2018. Still a long time, but less than a year.

So I reach out to them How to document curried functions?.

Please stand by TV screen

Radio silence

RIP doxdox.

slate

Slate screenshot

This is by far my favorite screenshot. Great theme and recent activity in the repo.

But how do I use it? At first glance, the documentation on the site seems comprehensive, but how do I write the docs?

It seems like I create markdown and the HTML is generated from that. Where do I put the markdown, what do I name the markdown? I have to use vagrant just for docs?

I’m putting this one on the back burner.

hm-doc

What: Generates simple markdown documentation from Hindley-Milner single line // comments and optional /* */ block comments in JavaScript code.

This seems interesting. Markdown generator for curried code.

VSCODE would’t understand much, but at least I would get my API docs written.

6 Stars though. Still gonna give it a try. I submitted an issue already.

Honorable mentions

ESDoc – Similar to JSDoc.

YUIDoc – Similar to JSDoc.

Autodoc – write tests in comments just above your JavaScript functions

React Styleguidist – Isolated React component development environment with a living style guide

Storybook – Interactive UI component dev & test: React, React Native, Vue, Angular

Source: dev