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 ...
For further actions, you may consider blocking this person and/or reporting abuse
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.
Do the minifiers and such pull the comments/documentation out?