While researching what developers love about their favorite API documentation sets for my last post, I also investigated what tools the API teams use to generate the documentation. Some teams just hand-write HTML, but most use code-based generators for the references and/or some sort of markdown for writing the guides. A good tool or toolset should make it easy to update the reference for every API release (outdated documentation should be avoided at all costs) and painless to write documentation about how to use the API (writing is one of those tasks that people put off - the less obstacles there are, the better). Based on my experience, here are the questions you should be asking when picking a tool:
- What is the input for the tool?
- Does it run over code and/or supplementary files? It's great to use a tool to automate your reference generation, but even better if you can use the same tool to write your developer's guide as well.
- What languages will it process? If your API is written in multiple languages (like Flurry, the company I did this research for), you probably want to pick a tool that will work over all of them so you can have a consistent process and output.
- What style of comments does it parse? If you're already using comments to instruct your compiler, you won't want to use a different format just for the docs.
- What is the output for the tool? HTML is a must, even better if it can do multi-page and single-page. PDF and other formats can also be quite useful.
- What is it written in? It needs to work in your development environment, and ideally hook into your build system.
- How easy is it to customize for your needs? The ideal tool includes easy customization options that don't require digging into the code, but is also open-source in case they don't do it for you.
To give you an idea of (just a fraction of) what's out there, here is a breakdown of the documentation tools used by the APIs from the last post.
Multi-Language Generators
| Tool | Input files | Input language | Input comments | Output | Written in? | Examples |
|---|---|---|---|---|---|---|
| Natural Docs | In code or other files | C#, Perl, AS2, partial support for other languages. | JavaDoc, or custom "natural syntax" | HTML | Perl | jqPlot, Users list |
| Doxygen | In code or other files | C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C# | JavaDoc or QT style, with some support for other styles | HTML, TEX, RTF, PS, PDF, ... | C++ | KDE, Users list |
| docco | In code | CoffeeScript, JS, Ruby, Python | Markdown | HTML | CoffeeScript | data.js and drops.coffee |
| Sphinx | In code or other files | Python, C/C++ | RST | HTML, TEX, PDF | Python | Python, Django |
| DocBook | Generated from XML files | XML | HTML, PDF, CHM, RTF, ... | PHP | PHP.net |
Single Language Generators
| Tool | Input files | Input language | Input comments | Output | Written in? | Examples |
|---|---|---|---|---|---|---|
| JavaDoc | In code | Java | JavaDoc | HTML | Java | Android |
| joDoc | In code or other files | JS | Markdown | HTML | Perl | PhoneGap |
| JSDoc 3 | In code | JS | JSDoc | HTML | Java/JS | None yet, in beta. |
| JSDoc 2 (JsDoc-toolkit) | In code | JS | JSDoc | HTML | Java/JS | Google Maps API v3 |
| JSDuck | In code | JS | Markdown, HTML, some JSDoc tags | HTML | Ruby | Ext-JS 4 |
| ErlDocs | In code | Erlang | HTML | Erlang | ErlDocs.com |
If you're interested in exploring tools further, check out the Documentation Generators section of my Developer Support handbook and this nearly comprehensive comparison of documentation generators from Wikipedia. There are always new tools being built out there by developers not quite satisfied by the current offerings and going at it their own way - and that's a great thing for all of us.
Let me know in the comments what tools you use (or are building yourself!) and your experience with them.
No comments:
Post a Comment