June 23, 2014

cod: An Unassuming Documentation Generator

The software world is a complex, dynamic mess.

In the face of chaos, the modern programmer has learned to embrace adaptability over stability.

As a result, innovative new languages with entire ecosystems of libraries seem to form overnight, while powerful tools and services dramatically simplify our development process.

And yet, the dream of the ‘90s is still alive in our documentation tools.

Consider – just as an example – JavaScript: JSDoc and YUIdoc are two of the most popular documentation-generators available.

Both of them have a limited set of accepted @tags, which are heavily inspired by monolithic tools like doxygen. These aim to be all-in-one solutions for generating human-readable API docs, usually static HTML/CSS/JS.

But JavaScript is nothing like the classical languages those tools were designed for, and monolithic tools do not mix with the modular workflow of today’s web developers.

JavaScript has no formal definitions of namespaces, modules, events, mixins, or even classes, so why are we imposing a formal structure on our documentation style?

Not to mention that new programming patterns emerge all the time. I often make use of promises in my JavaScript projects, but there is nothing like @promise or @deferred in JSDoc or YUIDoc, which means I have to write a lot of this:

@return {Promise} A promise that resolves to a {Number}

…when this could have sufficed:

@promise {Number}

Furthermore, given the workflow of the modern developer, why do we let our documentation step on our toes by imposing a particular set of templates and markup languages?

These problems compound for multi-lingual projects. Since most doc-generators are language-specific, it’s likely that you’ll need to both write your docs in different styles, and export them to entirely different formats.

Frustration is the mother of invention.

Enter cod: #

Unlike doxygen/YUIDoc/JSDoc & friends, cod doesn’t try to do everything for you.

You write your docs in its flexible format, and it faithfully outputs JSON.

/**
@Something
  Text can go anywhere.
     Whitespace is preserved.
  @flag
  @property 42
  @string Hello, cod
  @nested
    @property
  @list A
  @list B
  @list C
*/

// Later...

/**
@Something:extension
  Tags can be "re-opened"
*/

{
  "Something": {
    "!text": "Text can go anywhere.\n   Whitespace is preserved.",
    "flag": true,
    "property": 42,
    "string": "Hello, cod",
    "nested": {
      "property": true
    },
    "list": ["A", "B", "C"],
    "extension": {
      "!text": "Tags can be \"re-opened\""
    }
  }
}

Use whatever tags you need.

Anything that isn’t a @tag is text.

It leaves your text untouched. You can process it as Markdown later. Or HTML. Or just keep it as plain text.

Once you have the JSON, feed it to whatever you want. Utilize your site’s existing templates and styles. Build an app that can consume multiple versions of your API docs. Easily compare specific versions at the structural level.

cod is language-agnostic; all it needs to know is the pattern that your project uses to denote a doc-block (i.e. /** and */).

cod is still very early in development, but I encourage you to try it in your next project.

npm install -g cod
cod -o api.json *.js # or *.go or *.cpp or ...
cod -b '###*' -e '###' -o api.json *.coffee
cod -b '{-*' -e '-}' -o api.json *.hs

If you have any suggestions or find any bugs (there will be bugs!), leave a note on the issues page.

Kudos