add bin docast

README.md

@@ -19,7 +19,59 @@ cd ./docast
 npm install
 ```
 
-## Basic Usage
+## CLI Usage
+From the command line you can use `docast` to pull comments out from javascript
+files and store into a json file or you can provide a javascript file to use to
+format the comments into some other form.
+
+### Help Text
+```
+$ docast --help
+Usage:
+  docast (-h | --help)
+  docast (-v | --version)
+  docast extract [-o <output>] <input_files>...
+  docast generate <formatter> <input_files>...
+
+Options:
+  -h --help               Show this help text
+  -v --version            Show docast version information
+Extract:
+  Parse docs from javascript files and output as json to a file
+  -o --output <output>    File to output to [default: out.json]
+  <input_files>           List of javascript files to fetch docs from
+Generate:
+  Provide a script used to generate documentation from the parsed docs
+  <formatter>             Script which exports a `function(comments)` used to generate docs from comments
+  <input_files>           List of javascript files to fetch docs from
+```
+
+### Extract
+```
+$ docast extract -o out.json ./lib/*.js
+$ cat out.js
+[{"name":"func1","params":[],"returns":[],"raises":[],"doc":"this is func1"}, ...]
+```
+
+### Generate
+#### formatter.js
+```javascript
+// simply print the name of each function we have documentation for
+module.exports = function(comments){
+    comments.forEach(function(comment){
+        console.log(comment.name);
+    });
+};
+```
+
+#### Usage
+```
+$ docast generate ./formatter.js ./lib/*.js
+func1
+func2
+```
+
+## Basic API Usage
 The below example shows how you can use DocAST to parse documentation data from
 your javascript source code.
 

bin/docast

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+var docast = require('docast');
+var docopt = require('docopt');
+var fs = require('fs');
+var path = require('path');
+
+var doc = [
+    'Usage:',
+    '  docast (-h | --help)',
+    '  docast (-v | --version)',
+    '  docast extract [-o <output>] <input_files>...',
+    '  docast generate <formatter> <input_files>...',
+    '',
+    'Options:',
+    '  -h --help               Show this help text',
+    '  -v --version            Show docast version information',
+    'Extract:',
+    '  Parse docs from javascript files and output as json to a file',
+    '  -o --output <output>    File to output to [default: out.json]',
+    '  <input_files>           List of javascript files to fetch docs from',
+    'Generate:',
+    '  Provide a script used to generate documentation from the parsed docs',
+    '  <formatter>             Script which exports a `function(comments)` used to generate docs from comments',
+    '  <input_files>           List of javascript files to fetch docs from',
+].join('\r\n');
+
+var args = docopt.docopt(doc, {version: require('../package.json').version});
+
+var comments = [];
+args['<input_files>'].forEach(function(file){
+    comments = comments.concat(docast.parse(file));
+});
+
+if(args.extract){
+    fs.writeFileSync(args['--output'], JSON.stringify(comments));
+} else if(args.generate){
+    var loc = path.join(process.cwd(), args['<formatter>']);
+    var formatter = require(loc);
+    formatter(comments);
+}

package.json

@@ -17,9 +17,13 @@
   },
   "homepage": "https://github.com/brettlangdon/docast",
   "dependencies": {
+    "docopt": "^0.4.1",
     "esprima": "^1.2.3"
   },
   "devDependencies": {
     "mocha": "^2.1.0"
+  },
+  "bin": {
+    "docast": "bin/docast"
   }
 }