Cod

An Unassuming Doc Format

(Documentus modestus)

/**
@SomeModule
  Text about @SomeModule

  @use_any_tag_you_want
  @property
    Text about @property
    @sub_property 42
  @list a
  @list b
  @list c
*/

{
  "SomeModule": {
    "!text": "Text about @SomeModule\n",

    "use_any_tag_you_want": true,
    "property": {
      "!text": "Text about @property",
      "sub_property": 42
    },
    "list": [ "a", "b", "c" ]
  }
}

"Stupid by Design"

Cod is not a documentation generator, per se.

Cod's format is language-agnostic.

Cod imposes no fixed set of @tags, and doesn't do any kind of code analysis.

Cod merely transforms your in-code docs into plain-old JSON. It's up to you to turn this JSON into something more human-readable.

This affords Cod's users a great deal of control:

Use any markup language in text sections (or don't).
Use a single doc format across multiple languages.
Use your existing website styles instead of writing themes.
Use domain-specific tags i.e. @model/@view/@controller

In other words, Cod may not be smart, but it's not stubborn, either.

Cod comes with an easy-to-use command-line tool, and a JavaScript API.

Why Cod?

Documentation generators such as Doxygen or JSDoc are great if you need nice-looking API docs as quickly as possible, but "all-in-one" solutions quickly become too cumbersome when you need finer control.

Here are some scenarios where Cod might be a good choice:

Multi-Language Projects

Since Cod is language-agnostic, it's possible to use the same doc format in all languages, and the resulting JSON can be fed to a single set of templates in your language/framework of choice.

This allows you to give your docs a cohesive structure and professional look without the need to create and maintain multiple custom doc-generator themes (typically one for each language).

Domain-Specific Docs

Most software is written using higher-level programming patterns (i.e. MVC).

Most doc-generators limit their @tags to the terminology of the languages it supports, (i.e. @class,@return, etc.) but Cod is language-agnostic, so any @tag is valid.

Cod allows you to use tags like @model, @view, and @controller — or @whatever — to more concisely describe the structure of your code.

Obscure Languages

Maybe you just don't have any other option.

Perhaps you're creating your own doc-generator.

Cod is a good "first-step" here, since it works with any language.

Install

Install with npm install -g cod.