This is an example format for the API reference documentation for a node module, in json

module-api-ref.json

{ type: 'module',
  name: 'cluster',
  desc: 'The long html description thing at the beginning, examples, etc.',
  events: 
   [ { type: 'event',
       name: 'fork',
       arguments: [ { name: 'worker', type: 'object', class: 'Worker' } ],
       desc: 'blahblah long html description' },
     { type: 'event',
       name: 'ready',
       arguments: [ { name: 'worker', type: 'object', class: 'Worker' } ],
       desc: 'help all the humans' } ],
  classes: 
   [ { type: 'class',
       name: 'Worker',
       classMethods: 
        [ { type: 'function',
            name: 'someClassMethod',
            return: 
             { type: 'boolean',
               desc: 'True if it worked.  Otherwise false.' },
            arguments: 
             [ { type: 'string', name: 'foo', optional: true, default: 'blerg' },
               { type: 'object',
                 name: 'settings',
                 options: 
                  [ { name: 'src', type: 'string', description: 'The source string' },
                    { name: 'dest',
                      type: 'string',
                      desc: 'The destination string' } ] } ] } ],
       methods: [ { type: 'function', name: 'sendMessage', arguments: [] } ],
       properties: 
        [ { name: 'someProperty', type: 'number', default: 100 },
          { name: 'otherProp',
            type: 'object',
            class: 'Worker',
            desc: 'An \'other worker\' property' } ],
       events: [ {} ] } ] }

This is an example of what would show up at http://nodejs.org/api/cluster.json.

Each of the globals (process, global, errno, console, Buffer, and the timeout stuff) will be an object of type: 'global'. module, exports, require, __filename, and __dirname will be an object of type: 'var', to indicate that it's module-local.

The root at /all.json will have a globals section, a modules section, and a vars section.

Any object anywhere can have a volatility rating. See: https://gist.github.com/1776425

I think there need some internal boolean.
In this case Worker class is an internal constructor function, but you can using instanceof cluster.Worker and its methods and events is allowed.

Also properties like cluster.workers is a type:map but is values are Worker objects, how do we specify that.

It would also be nice with readable and writable labels.