use jsjsdoc for some documentation

autopulated · autopulated · commit 59d1f35f5180 · 2014-05-04T00:53:11.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,33 @@
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# Deployed apps should consider commenting this line out:
+# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
 node_modules
-.*.swp
+
+# Swap files
 .*.swo
+.*.swp
 .*.swn
+
+# OS Files
+.DS_Store
diff --git a/gruntfile.js b/gruntfile.js
@@ -0,0 +1,38 @@
+module.exports = function(grunt) {
+
+  grunt.initConfig({
+    pkg: grunt.file.readJSON('package.json'),
+    jshint: {
+      files: ['*.js'],
+      options: {
+        // options here to override JSHint defaults
+        globals: {
+          jQuery: true,
+          console: true,
+          module: true,
+          document: true
+        }
+      }
+    },
+    jsjsdoc: {
+      main: {
+        files: {'docs/main.md': ['*.js']},
+      }
+    },
+    watch: {
+      main: {
+        files: ['*.js'],
+        tasks: ['jshint', 'jsjsdoc']
+      }
+    }
+  });
+
+  grunt.loadNpmTasks('grunt-contrib-watch');
+  grunt.loadNpmTasks('grunt-contrib-jshint');
+  grunt.loadNpmTasks('grunt-jsjsdoc');
+
+  grunt.registerTask('default', ['jshint', 'jsjsdoc', 'watch']);
+  
+};
+
+
diff --git a/lib.js b/lib.js
@@ -1,5 +1,25 @@
+/**
+ * # lib.js
+ *
+ * Define the Coggle API classes
+ *
+ */
+
+/*! imports */
 var unirest   = require('unirest');
 
+/**
+ * Create a new Coggle API Node object
+ *
+ * @constructor
+ * @class CoggleApiNode
+ *
+ * @param {CoggleApiDiagram} diagram of this node
+ * @param {Object} resource representing this node
+ *
+ * @return constructs an instance of CoggleApi
+ * @api public
+ */
 var CoggleApiNode = function CoggleApiNode(coggle_api_diagram, node_resource){
   this.diagram = coggle_api_diagram;
   this.id      = node_resource._id;
@@ -13,13 +33,13 @@ var CoggleApiNode = function CoggleApiNode(coggle_api_diagram, node_resource){
 
   this.children = [];
   if('children' in node_resource){
-    node_resource.children.forEach(function(child){
-      var child = new CoggleApiNode(coggle_api_diagram, child);
+    node_resource.children.forEach(function(child_resource){
+      var child = new CoggleApiNode(coggle_api_diagram, child_resource);
       child.parent_id = this.id;
       this.children.push_back(child);
     });
   }
-}
+};
 CoggleApiNode.prototype = {
   addChild: function addChild(text, offset, callback){
     var self = this;
@@ -42,11 +62,26 @@ CoggleApiNode.prototype = {
   }
 };
 
+/**
+ * Create a new instance of a Coggle API Diagram object.
+ *
+ * @constructor
+ * @class CoggleApi
+ *
+ * @param {CoggleApi} api client to be used by this diagram
+ * @param {Object} resource describing this diagram. Should have at least the
+ *                 following fields:
+ *                   * _id: ID of the diagram
+ *                   * title: title of the diagram
+ *
+ * @return constructs an instance of CoggleApi
+ * @api public
+ */
 var CoggleApiDiagram = function CoggleApiDiagram(coggle_api, diagram_resource){
     this.apiclient = coggle_api;
     this.id        = diagram_resource._id;
     this.title     = diagram_resource.title;
-}
+};
 CoggleApiDiagram.prototype = {
   webUrl: function webUrl(){
     return this.replaceId(this.apiclient.baseurl+'/diagram/:diagram');
@@ -71,43 +106,116 @@ CoggleApiDiagram.prototype = {
 };
 
 
+/**!jsjsdoc
+ *
+ * doc.CoggleApi = {
+ *    $brief: "The Coggle API client.",
+ * }
+ *
+ * doc.CoggleApi.$constructor = {
+ *   $brief: "Create a new instance of the Coggle API client.",
+ *   $parameters: {
+ *     options: "Options: {}"
+ *   }
+ * }
+ *
+ */
 var CoggleApi = function CoggleApi(options){
-    this.baseurl = options.base_url || 'http://localdev.coggle.it';
-    this.token   = options.token;
-}
-CoggleApi.prototype = {
-  post: function post(endpoint, body, callback){
-    unirest.post(this.baseurl + endpoint + '?access_token=' + this.token)
-      .type('json')
-      .send(body)
-      .end(function(response){
-        if(!response.ok)
-          return callback(new Error('POST ' + endpoint + ' failed:' + (response.body && response.body.details) || response.error));
-        return callback(false, response.body);
-    });
-  },
-  get: function get(endpoint, callback){
-    unirest.get(this.baseurl + endpoint + '?access_token=' + this.token)
-      .type('json')
-      .end(function(response){
-        if(!response.ok)
-          return callback(new Error('GET ' + endpoint + ' failed:' + (response.body && response.body.details) || response.error));
-        return callback(false, response.body);
-    });
-  },
+  this.baseurl = options.base_url || 'https://coggle.it';
+  this.token   = options.token;
+  if(!options.token)
+      throw new Error("you must provide a user's authentication token");
 
-  createDiagram: function createCoggle(title, callback){
-    // callback should accept(error, diagram)
-    var self = this;
-    var body = {
-      title:title
-    };
-    this.post('/api/1/diagrams', body, function(err, body){
-      if(err)
-        return callback(new Error('failed to create coggle: ' + err.message));
-      return callback(false, new CoggleApiDiagram(self, body));
-    });
-  },
+  CoggleApi.prototype = {
+    /**!jsjsdoc
+     *
+     * doc.CoggleApi.post = {
+     *   $api: "private",
+     *   $brief: "POST to an endpoint on the Coggle API",
+     *   $parameters: {
+     *     endpoint: {
+     *       $type: "String",
+     *       $brief: "URL of endpoint to post to (relative to the domain)",
+     *       $example: "Use `/api/1/diagrams` to create a new diagram."
+     *     },
+     *     body: "The body to post. Will be converted to JSON.",
+     *     callback: {
+     *       $type: "Function",
+     *       $brief: "Callback accepting (error, body) that will be called "+
+     *               "with the result. The response returned from the server "+
+     *               "is parsed as JSON and returned as `body`.",
+     *     }
+     *   }
+     * }
+     */
+    post: function post(endpoint, body, callback){
+      unirest.post(this.baseurl + endpoint + '?access_token=' + this.token)
+        .type('json')
+        .send(body)
+        .end(function(response){
+          if(!response.ok)
+            return callback(new Error('POST ' + endpoint + ' failed:' + (response.body && response.body.details) || response.error));
+          return callback(false, response.body);
+      });
+    },
+    /**!jsjsdoc
+     *
+     * doc.CoggleApi.get = {
+     *   $api: "private",
+     *   $brief: "GET from an endpoint on the Coggle API",
+     *   $parameters: {
+     *     endpoint: {
+     *       $type: "String",
+     *       $brief: "URL of endpoint to get from (relative to the domain)"
+     *     },
+     *     callback: {
+     *       $type: "Function",
+     *       $brief: "Callback accepting (error, body) that will be called "+
+     *               "with the result. The response returned from the server "+
+     *               "is parsed as JSON and returned as `body`.",
+     *     }
+     *   }
+     * }
+     */
+    get: function get(endpoint, callback){
+      unirest.get(this.baseurl + endpoint + '?access_token=' + this.token)
+        .type('json')
+        .end(function(response){
+          if(!response.ok)
+            return callback(new Error('GET ' + endpoint + ' failed:' + (response.body && response.body.details) || response.error));
+          return callback(false, response.body);
+      });
+    },
+  
+    /**!jsjsdoc
+     *
+     * doc.CoggleApi.createDiagram = {
+     *   $brief: "Create a new Coggle diagram.",
+     *   $parameters: {
+     *     title: {
+     *       $type: "String",
+     *       $brief: "Title for the created diagram."
+     *     },
+     *     callback: {
+     *       $type: "Function",
+     *       $brief: "Callback accepting (error, CoggleApiDiagram)",
+     *     }
+     *   }
+     * }
+     */
+    createDiagram: function createCoggle(title, callback){
+      // callback should accept(error, diagram)
+      var self = this;
+      var body = {
+        title:title
+      };
+      this.post('/api/1/diagrams', body, function(err, body){
+        if(err)
+          return callback(new Error('failed to create coggle: ' + err.message));
+        return callback(false, new CoggleApiDiagram(self, body));
+      });
+    },
+  };
 };
 
 module.exports = CoggleApi;
diff --git a/readme.md b/readme.md
@@ -1,6 +1,6 @@
-## Coggle API Javascript Client
+# Coggle API Javascript Client
 
-### Basic Use
+## Basic Use
 See [coggle-issue-importer](http://github.com/coggle/coggle-issue-importer) for
 a complete example application, including authentication.
 
@@ -15,25 +15,38 @@ coggle.createDiagram(
     "My New Coggle"
     function(err, diagram){
         if(err)
-            raise err;
+            throw err;
         console.log("created diagram!", diagram);
     }
 );
 ```
 
 
-### API Documentation
+# API Documentation
+##Class `CoggleApi`
+The Coggle API client.
 
-#### CoggleApi
-##### constructor
-##### createDiagram
+###Constructor
+Create a new instance of the Coggle API client.
 
-### CoggleApiDiagram 
-##### constructor
-##### getNodes
-##### webUrl
+###Method `post`
+POST to an endpoint on the Coggle API
 
-#### CoggleApiNode
-##### constructor
-##### addChild
+Parameters:
+  * **`endpoint`** type: `String`URL of endpoint to post to (relative to the domain)
+  * **`body`**The body to post. Will be converted to JSON.
+  * **`callback`** type: `Function`Callback accepting (error, body) that will be called with the result. The response returned from the server is parsed as JSON and returned as `body`.
 
+###Method `get`
+GET from an endpoint on the Coggle API
+
+Parameters:
+  * **`endpoint`** type: `String`URL of endpoint to get from (relative to the domain)
+  * **`callback`** type: `Function`Callback accepting (error, body) that will be called with the result. The response returned from the server is parsed as JSON and returned as `body`.
+
+###Method `createDiagram`
+Create a new Coggle diagram.
+
+Parameters:
+  * **`title`** type: `String`Title for the created diagram.
+  * **`callback`** type: `Function`Callback accepting (error, CoggleApiDiagram)
