Let's talk about the state of auto-generated documentation tools for JavaScript
Tags: discuss, javascript, tools
Published: 2018-10-15 16:56:58

After I finish [hand writing almost a thousand lines of documentation](https://github.com/joelnet/MojiScript/blob/master/API.md), 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:

```javascript
// 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](http://usejsdoc.org/about-getting-started.html)

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](https://github.com/jsdoc3/jsdoc/issues/1286) and check the date. October 2016.

![rage face](https://thepracticaldev.s3.amazonaws.com/i/gwr7j43nhreztq77lbfb.png)

Okay... RIP JSDoc.

# [Minami](https://github.com/nijikokun/minami)

![Minami screenshot](https://camo.githubusercontent.com/03e6d3687da4f4e05c2d4f9bd2b711f5f113a8c0/687474703a2f2f692e696d6775722e636f6d2f725043494671542e706e67)

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](https://github.com/neogeek/doxdox)

![doxdox screenshot](https://github.com/neogeek/doxdox/raw/master/screenshot.jpg)

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?](https://github.com/neogeek/doxdox/issues/73).

![Please stand by TV screen](https://thepracticaldev.s3.amazonaws.com/i/lsaw8wtk02trwgwio0rp.jpeg)

Radio silence

RIP doxdox.

# [slate](https://github.com/lord/slate)

![Slate screenshot](https://raw.githubusercontent.com/lord/img/master/screenshot-slate.png)

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](https://github.com/JesterXL/hm-doc)

> **What**: Generates simple markdown documentation from [Hindley-Milner](https://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system) 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](https://esdoc.org/) - Similar to JSDoc.

[YUIDoc](http://yui.github.io/yuidoc/) - Similar to JSDoc.

[Autodoc](https://github.com/dtao/autodoc) - write tests in comments just above your JavaScript functions

[React Styleguidist](https://github.com/styleguidist/react-styleguidist) - Isolated React component development environment with a living style guide

[Storybook](https://github.com/storybooks/storybook) - Interactive UI component dev & test: React, React Native, Vue, Angular

# So what's next?

To be honest, I am not happy with any of these solutions and I'm about this close to rolling my own solution.

What solutions do you use to generate documentation for your code? How is it working out for you?

My articles are very Functional JavaScript heavy, if you need more, follow me here, or on Twitter [@joelnet](https://twitter.com/joelnet)!

**More articles**
[Let's make a DEV.to CLI... together](https://dev.to/joelnet/lets-make-a-devto-cli-together-4eh1)
[Ask me dumb questions about functional programming](https://dev.to/joelnet/ask-me-dumb-questions-about-functional-programming-bho)

![Cheers!](https://thepracticaldev.s3.amazonaws.com/i/6jsy3a866frzp3u5oda0.jpg)