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

JavaScript Joel on October 15, 2018

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 bes... [Read Full]
 

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!

 

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.

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

 

I have heard good stuff about docco, tried it myself and its nice and pretty easy (last commit however was like 6 months ago). Might be a bit off topic since it's more of a one-size-fits all coding style guide bit well worth the setup time in my humble opinion. What i liked was the high hackability since the core is Little more than 100+ lines of code

 

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.

 

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!

 

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.

 

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.

code of conduct - report abuse