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
Top comments (22)
This is a really great, thorough evaluation of auto-doc tools! While I do not work much in Javascript and don't know the landscape and tools very well, I have been building a general-purpose documentation generator for quite some time, Orchid. It currently supports generating docs for Java, Kotlin, Swift, and CSS, but I am starting to look into possibilities for documenting other languages as well, especially Javascript!
As you've noticed, there are lots of tools, and all of them ultimately do one thing well but usually don't look that great, and if you're looking for multiple forms of documentation you'll end up needing multiple different tools for each. Orchid is designed to incorporate many different kinds of docs in one tool (code docs, wikis, changelogs, blogs, or anything else), with great theming capabilities so you make easily make it look exactly how you want, and full-text static searching capabilities to make it easy to browse the docs. Strikt.io just went live with Orchid docs, and is a great example of what kinds of sites Orchid can generate.
If you do end up rolling your own solution, or if you know of any of these tools that can generate JSON, I would love to help get it integrated into Orchid.
My "roll my own" solution would probably just solve my problem. I wouldn't want to maintain anything. Maybe it would be better for me to contribute to another project so that I don't have to maintain it afterwards. I already have too much on my plate. lol.
I'm just surprised this section of the ecosystem still isn't as evolved yet.
I'm glad you are looking at other areas like JavaScript. Documentation is something that should be mandatory for every project and tools like this that ease the pain give people less excuses to not do it.
Cheers!
I found this recently, which would be a great help if you do choose to roll your own docs: github.com/eslint/doctrine
doctrine takes a jsdoc block and converts it into an AST.
I working on an abandoned project and I have to set up the automated deployment of docs(from JSDOC comments in the main codebase).
So what I understood is that, I have jsdoc comments in the code, I to make (most probably) show them in on a HTML page such that when the user makes any change in the base code comments the HTML page show the change.
I need help as I couldn't find any way to do it. Can you please guide me how can I do it. I would be grateful if you could do any type of help.
I got to know that previously doclet.io could have been used for that but now what service is defunct.
Thanks!
If your codebase is already using JSDoc, check out their Templates and Build Tools section:
github.com/jsdoc/jsdoc
There's a couple different automation tools to choose from in there.
This may come as silly, but I am new to documentation.
I tried to work with what you said but the couldn't find any solution.
Problem is that I have many Nodejs files with JSDoc comments in them. I can 'run jsdoc' command on each file but then I'll end up having a lot of 'index.html' files that I would be needed to connect somehow. Also if there comes a change in the comment in one file then I would need to change that file manually. Canceling the point that we are trying to get automated documentation that changes as the source code changes.
I don't think templates would be helpful in this case. Please help me if you can, I would be grateful. Thanks!
I ended up abandoning the approach of creating JSDoc html files from the code comments. I instead just manually created the docs. So I don't really know a good solution for it.
I ended up going with this instead: docz.site/
I would also start using docz then. Thanks!
Sure I'll look into it. Thanks a lot!
I've been using jsdoc for like 2 years now and to be honest I am completely satisfied. Even I in my company we wrote an awesome template: github.com/SoftwareBrothers/better... - It took like 2 days and now we have full control of the documentation output.
Hey, could you share what you ended up doing? it's 2019 and it still seems rather tough to find a good tool for JSDocs...
I really was hoping for something that support Mixins but no luck so far - maybe you know more?
I abandoned the auto generated docs. They just didn't work out. I went with docz.site.
Awesome, I am also using docz.site very easy to customize and create
I have the exact same problem.
I always document my functions with jsDoc comments for IDE autocompletion, but I would also like to be able to generate html or markdown.
If you end up doing your own thing, get in touch, I would love to help you out.
Will do. Right now I am exploring the HM-DOC option. This one seems to be tailor made for curried functions. And all the functions I need to document are curried, so this one might work best.
I'll let you know when I find out more :)
Cheers!
Hi Joel, I've been trying to solve similar problems for years, and eventually started a company to explore a different approach. Rather than scanning "old-school" code comments to create documentation, we built CodeStream to make it easier to capture conversation as documentation (of a sorts) right in your source code. No, it's not nearly as formal as documenting input and output parameters, but it allows you to ask questions about code and get responses much more easily, and then saves those Qs&As as comment threads tied to the codeblocks they refer to.
We wrote up the ideas behind CodeStream in our Master Plan blog post.
I'd love to hear your feedback.
Are there any auto-documenting tools that are standardized against different languages and environments? As someone who does some JS but some of various other things regularly I sometimes feel like I'd want more multilingual tools when it comes to things like docs.
Hello this is a great post! I have a question for you guys (I’m in absolutely non-technical person) my programmer is customizing a poorly written code (please don’t judge that’s another discussion for another day) that has a Huge js filed and they have a front end developer working on redesigning the site. Is there a way to run a script and get a « inventory » of all jQuery selectors/classes/attributes etc. So that we can guide the front end developer .
I haven't seen anything like that. You might have to create something custom to get that info.
documentationjs works pretty well for es6+flow+typescript
I'll investigate this. It seems like their project is also light on documentation. I'd like to see what output is generated. Also some examples on how to use it.