add docs via dox

HISTORY.md

@@ -5,7 +5,6 @@ Wishlist
 * Spawning 4 workers with `spark` is enough to have 4 parallel HTTP clients hammering Riak?
 * Provide an accurate clientId, bound to user/machine (even in the browser?) - randomizing it on client init is a bad solution
 
-=> dox
 => vows / merge airline tests and introduce fake passengers with faker
 => check possible merge with technoweenie/nori
 => issue 6 / test jquery version / transporter for jquery
@@ -20,6 +19,7 @@ DONE
 => links uri-unescape
 => added `db.error` convenience function to check for errors - still don't like node's `function(err, response)` standard
 => working "keys" (http://github.com/visionmedia/keys) implementation
+=> API docs via dox
 
 0.2.3 / 2010-06-21
 ------------------

docs/doc-gen.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+dox --title "riak-js" --desc "Extensible Javascript library for accessing Riak" \
+ ../lib/index.js ../lib/riak.js ../lib/mapper.js ../lib/meta.js > docs.html

docs/index.html

@@ -65,6 +65,9 @@ <h1>riak-js</h1>
       <div>
         <h4>Extensible Javascript library for accessing Riak, with<br/> implementations for <a href="http://nodejs.org">node.js</a> and <a href="http://jquery.com">jQuery</a>.</h4>
 
+        <em>The client is currently undergoing refactoring &mdash; the jQuery version does not work.
+          I'll try to fix this asap</em>
+
                 <pre>
 <code>db.save('airlines', 'KLM', {fleet: 111, alliance: 'SkyTeam'}, { links:
   [{ bucket: 'flights', key: 'KLM-8098', tag: 'cargo' },
@@ -78,7 +81,13 @@ <h4>Extensible Javascript library for accessing Riak, with<br/> implementations
           <li>Focused on developer experience – clean API with added sugar</li> 
           <li>Features all basic HTTP operations, plus link walking and map/reduce with chainable phases</li> 
           <li>Tested on Riak 0.10+, node.js 0.1.97+ and jQuery 1.4+</li>
-        </ul> 
+        </ul>
+
+        <ul> 
+          <li>Code: <a href="http://github.com/frank06/riak-js">frank06/riak-js</a></li> 
+          <li>Documentation: <a href="docs.html">API docs</a></li> 
+          <li>License: <a href="http://opensource.org/licenses/mit-license.php">MIT</a></li>
+        </ul>
 
         <h3>node.js setup</h3> 
 

lib/index.js

@@ -1,3 +1,10 @@
+/**
+ * Get a riak-js client
+ *
+ * @param {Object} Initial options, that will apply for the whole session
+ * @return {Riak} The riak-js client
+ * @api public
+ */
 exports.getClient = function(options) {
   var Riak = require('./riak-node')
   return new Riak(options)

lib/mapper.js

@@ -1,25 +1,59 @@
+/**
+ * Module dependencies
+ */
 var utils = require('./utils')
 
+/**
+ * @api private
+ */
 function Mapper(phases, riak) {
   this.phases = phases ;
   this.riak = riak;
 }
 
+/**
+ * Add one or more *map* phases to the Map/Reduce job
+ *
+ * @param {Object} One (function, string, or object containing `source`, `name`, `args`, etc) or more phases (each one contained in an Array)
+ * @return {Mapper} To be able to chain until `#run()` is called
+ * @api public
+ */
 Mapper.prototype.map = function(phase, args) {
   this.addPhases(utils.makePhases("map", phase, args))
   return this;
 }
 
+/**
+ * Add one or more *reduce* phases to the Map/Reduce job
+ *
+ * @param {Object} One (function, string, or object containing `source`, `name`, `args`, etc) or more phases (each one contained in an Array)
+ * @return {Mapper} To be able to chain until `#run()` is called
+ * @api public
+ */
 Mapper.prototype.reduce = function(phase, args) {
   this.addPhases(utils.makePhases("reduce", phase, args))
   return this;
 }
 
+/**
+ * Add one or more *link* phases to the Map/Reduce job
+ *
+ * @param {Object} One (function, string, or object containing `source`, `name`, `args`, etc) or more phases (each one contained in an Array)
+ * @return {Mapper} To be able to chain until `#run()` is called
+ * @api public
+ */
 Mapper.prototype.link = function(phase) {
   this.addPhases(utils.makePhases("link", phase))
   return this;
 }
 
+/**
+ * Run the Map/Reduce job
+ *
+ * @param {Array} for a list of `[bucket, key]`, or {String} for a bucket name (*warning*: it has to list the bucket's keys)
+ * @return {Function} A function that takes a callback as its only input
+ * @api public
+ */
 Mapper.prototype.run = function(inputs, options) {
   options = utils.ensure(options);
   options.interface = 'mapred';
@@ -41,6 +75,9 @@ Mapper.prototype.run = function(inputs, options) {
   return this.riak.execute('', options);
 }
 
+/**
+ * @api private
+ */
 Mapper.prototype.addPhases = function(phases) {
   var self = this;
   phases.forEach(function(phase) {

lib/meta.js

@@ -1,5 +1,13 @@
+/**
+ * Module dependencies
+ */
 var utils = require('./utils')
 
+/**
+ * Constructor
+ *
+ * @api private
+ */
 function Meta(headers, interface, key, statusCode) {
   this.headers = headers;
   this.key = key;
@@ -8,21 +16,42 @@ function Meta(headers, interface, key, statusCode) {
   this.interface = interface;
 }
 
+/**
+ * Removes a link from the current list of links
+ *
+ * @param {Object} Link, such as `{bucket: 'bucket', key: 'mykey'}`
+ * @api public
+ */
 Meta.prototype.removeLink = function(link) {
   this.headers.link = this.makeLinks(this.links.filter(function(n) {
     return n.bucket !== link.bucket || n.key !== link.key
   }))
 }
 
+/**
+ * Link getter
+ *
+ * @return {Array} All the links in the current list of links
+ * @api public
+ */
 Meta.prototype.__defineGetter__('links', function() {
   return utils.stringToLinks(this.headers.link)
 })
 
+/**
+ * Link setter (one, or more in an Array)
+ *
+ * @param {Object} {Array} Link(s)
+ * @api public
+ */
 Meta.prototype.__defineSetter__('links', function(links) {
   if (!utils.isArray(links)) links = [links]
   this.headers.link = (this.headers.link ? this.headers.link + ", " : "") + this.makeLinks(links)
 })
 
+/**
+ * @api private
+ */
 Meta.prototype.makeLinks = function(links) {
   var self = this;
   return links.map(function(link) {