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.

Okay... RIP JSDoc.

Minami

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

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?.

Radio silence

RIP doxdox.

slate

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

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!

More articles
Let's make a DEV.to CLI... together
Ask me dumb questions about functional programming