Good JS API Documentation is Hard

[DamonOehlman]

My current observation is that good JS API documentation is hard, if not impossible to write with existing popular tools (e.g. JSDoc). While there are some newer tools available understanding how to get started with these tools is not clear.

My feeling is that developers should be rewarded for documenting their code, regardless of the special formatting they use. If they do choose to use some special flags then the quality of the generated output is enhanced. The general principle being that a little more effort improves the generated documentation a little, rather than if you jump through hoops 1-7 then you end up with awesome docs, otherwise you get none.

If you have found tools that you think produce excellent docs (reference examples: PopcornJS API and PhoneGap API) then please let me know. From what I can tell though, excellent API docs are maintained through separate repos and not generated from original code sources.

[dseif]

I agree that writing good docs are hard, it was something that took us a long time for Popcorn.js and is still very much a work in progress.

For writing the docs and keeping them version controlled I loved using jekyll and keeping it all on github ( https://github.com/dseif/popcorn-docs ) as we get pull requests and issues filed from time to time. Once we got the docs up and running adding a new doc or editing an old was pretty pain free, so that was a big plus.

If you're interested in Jekyll I would take a look at there install instructions as they are pretty good. I also noticed you were using this as somewhat of a blog, which Jekyll is great for managing and so on ( see http://captnemo.in/blog/2011/09/19/jekyll/ ).

If you ever have any questions about the docs or what we did feel free to drop by the #popcorn channel on irc.mozilla.org!

[davebalmer]

PhoneGap was, last I checked, using a modified version of JOdoc, which is markdown based. I'm a huge fan of markdown in general; it's simple, looks good as plaintext, and these days tools like github support it very well. I agree that crafted docs are generally better than generated docs, but all require more effort than your average developer has the time, inclination or even skill to produce. I'd love to see more projects get professional doc writers involved, and less focus on "making it easy" for developers to create docs themselves. I mean, first drafts, sure. But professional docs require professional doc writers.

[DamonOehlman]

Thanks for the responses guys. After spending yesterday experimenting with esprima and custom regex based parsing, I'm thinking that we are definitely moving beyond what a code-driven documentation tool can provide.

The number of different patterns and styles of coding just pure Javascript makes writing an effective and useful code-driven API documentation generator a pretty difficult task, and generally results in a tool suited to one particular style (primarily that of the authors).

As I was going to sleep last night, I had a half-second thought about turning the problem on it's head. Rather than attempting to write a tool that extracts meaningful, contextual API docs from code, what if we were to focus on creating a DSL that described a JS API effectively? The DSL would have provision for both the describing the functions and methods in a way that allowed some automated testing (TypedJS style for example) and also comments that could be used to generate the core of meaningful documentation.

I'm going to have a play with this in my free time over the next couple of days, but given both of your experience would definitely value any feedback that you might have :)

Cheers, Damon.

[vmx]

For MapQuery we use jodoc (the js port), which is also used by Phonegap. When you read the MapQuery source code the first time, the inline comments look distracting. But if you actually code, it works out really well. I often find typos/small bugs in the documention while I'm coding.

[DamonOehlman]

Thanks Volker - that's a good example of good usage of jodoc, I'm sure @davebalmer will be pleased to see it :)