mongoscope-client/bin/docs.js

shush

#!/usr/bin/env node
var dox = require('dox'),
  fs = require('fs');

var methods = dox.parseComments(
  fs.readFileSync(__dirname + '/../lib/client.js', 'utf-8'), {raw: true});

var badges = {
  deprecated: '![deprecated](http://b.repl.ca/v1/stability-deprecated-red.png)',
  prototype: '![prototype](http://b.repl.ca/v1/stability-prototype-orange.png)',
  development: '![development](http://b.repl.ca/v1/stability-development-yellow.png)',
  production: '![production](http://b.repl.ca/v1/stability-production-green.png)'
};

var apis = [];
methods.map(function(method){
  if(method.ignore || method.isPrivate) return;
  if(method.description.full === '@ignore') return;

  var stability,
    isProperty = false,
    params = [],
    args = [],
    options = [],
    todos = [],
    examples = [],
    streamable = false;

  if(!method.ctx){
    if(method.code.indexOf('Client.prototype') > -1){
      isProperty = true;
      method.ctx = {
        name: /Client.prototype, '(\w+)',/.exec(method.code)[1]
      };
    }
    else {
      return console.log('huh?', method);
    }
  }


  method.tags.map(function(tag){
    var matches;

    if(tag.type === 'param'){
      tag.optional = (tag.name.indexOf('[') === 0);
      tag.name = tag.name.replace('[', '').replace(']', '');
      args.push(tag.name);

      return params.push(tag);
    }
    if(tag.type === 'option'){
      // {Boolean} allowDiskUse
      matches = /\{(\w+)\} (\w+)/.exec(tag.string);
      tag.types = [matches[1]];
      tag.name = matches[2];
      return options.push(tag);
    }
    if(tag.type === 'example'){
      matches = /([\w\d\/\:\.]+) (.*)/.exec(tag.string);
      return examples.push({
        name: matches[2],
        url: matches[1]
      });
    }
    if(tag.type === 'stability') return stability = tag.string;
    if(tag.type === 'streamable') return streamable = true;
    if(tag.type === 'todo') todos.push(tag.string);
  });

  if(!isProperty){
    if(args.indexOf('opts') === -1 && args.indexOf('params') === -1 && options.length > 0){
      args.push('opts');
      var description = '\n' + options.map(function(opt){
        return '    - `' + opt.name + '` (' + opt.types.join('|') + ')';
      }).join('\n') + '\n';

      params.push({
        name: 'opts',
        optional: true,
        types: ['Object'],
        description: description
      });
    }
    if(args.indexOf('fn') === -1){
      args.push('fn');
      params.push({
        name: 'fn',
        optional: streamable || false,
        types: ['Function'],
        description: 'Called when the request is complete `(err, data)`'
      });
    }
  }

  apis.push({
    name: method.ctx.name,
    isProperty: isProperty,
    stability: stability,
    streamable: streamable,
    description: method.description.summary,
    params: params,
    args: args,
    options: options,
    todos: todos,
    source: method.code,
    examples: examples
  });
});

apis.map(function(api, i){
  if(i === 0) return; // @todo handle module level docs...

  if(api.isProperty){
    console.log('### mongoscope.' + api.name + '\n');
  }
  else{
    console.log('### mongoscope.' + api.name + '('+api.args.join(', ')+')\n');
  }

  console.log(badges[api.stability]);
  console.log('\n' + api.description);

  if(api.examples.length > 0){
    console.log('#### Examples\n');
    api.examples.map(function(example){
      console.log('- ['+example.name+']('+example.url+')');
    });
    console.log();
  }

  if(!api.isProperty){
    console.log('#### Parameters\n');
    api.params.map(function(param){
      console.log('- `'+param.name+'` ('+(param.optional ? 'optional' : 'required')+', '+param.types.join('|')+') ' + (param.description ? '... '+ param.description : ''));
    });
    console.log();
  }

  if(api.todos.length > 0){
    console.log('#### Todo\n');
    api.todos.map(function(t){
      console.log('- [ ] ' + t);
    });
    console.log();
  }
});