Add JSDoc comments

lib/storage-service.js

@@ -9,9 +9,14 @@ var File = require('./models/file');
 module.exports = StorageService;
 
 /**
- * @param options The options to create a provider
+ * Storage service constructor.  Properties of options object depend on the storage service provider.
- * @returns {StorageService}
+ *
- * @constructor
+ * 
+ * @options {Object} options The options to create a provider; see below;
+ * @prop {Object} connector <!-- What is this? -->
+ * @prop {String} provider Use 'filesystem' for local file system.  Other supported values are: 'amazon', 'rackspace', 'azure', and 'openstack'. 
+ * @prop {String} root With 'filesystem' provider, the path to the root of storage directory.
+ * @class
  */
 function StorageService(options) {
   if (!(this instanceof StorageService)) {
@@ -42,6 +47,11 @@ function map(obj) {
    */
 }
 
+/**
+ * List all storage service containers.
+ * @param {Function} callback Callback function; parameters: err - error message, containers - object holding all containers.
+ */
+
 StorageService.prototype.getContainers = function (cb) {
   this.client.getContainers(function (err, containers) {
     if (err) {
@@ -54,6 +64,17 @@ StorageService.prototype.getContainers = function (cb) {
   });
 };
 
+/**
+ * Create a new storage service container.  Other option properties depend on the provider.
+ * 
+ * @options {Object} options The options to create a provider; see below;
+ * @prop {Object} connector <!-- WHAT IS THIS? -->
+ * @prop {String} provider Storage service provider. Use 'filesystem' for local file system.  Other supported values are: 'amazon', 'rackspace', 'azure', and 'openstack'. 
+ * @prop {String} root With 'filesystem' provider, the path to the root of storage directory.
+ * @prop {String} 
+ * @param {Function} callback Callback function.
+ */
+
 StorageService.prototype.createContainer = function (options, cb) {
   options = options || {};
   if ('object' === typeof options && !(options instanceof storage.Container)) {
@@ -65,17 +86,33 @@ StorageService.prototype.createContainer = function (options, cb) {
   });
 };
 
+/**
+ * Destroy an existing storage service container.
+ * @param {Object} container Container object.
+ * @param {Function} callback Callback function.
+ */
 StorageService.prototype.destroyContainer = function (container, cb) {
   return this.client.destroyContainer(container, cb);
 };
 
+/**
+ * Look up a container by name.
+ * @param {Object} container Container object.
+ * @param {Function} callback Callback function.
+ */
 StorageService.prototype.getContainer = function (container, cb) {
   return this.client.getContainer(container, function (err, container) {
     return cb(err, map(container));
   });
 };
 
-// File related functions
+/**
+ * Get the stream for uploading
+ * @param {Object} container Container object.
+ * @param {String} file  IS THIS A FILE?
+ * @options options See below.
+ * @param callback Callback function
+ */
 StorageService.prototype.uploadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
     cb = options;
@@ -88,6 +125,13 @@ StorageService.prototype.uploadStream = function (container, file, options, cb)
   return this.client.upload(options, cb);
 };
 
+/**
+ * Get the stream for downloading.
+ * @param {Object} container Container object.
+ * @param {String} file Path to file.
+ * @options {Object} options See below. <!-- What are the options -->
+ * @param {Function} callback Callback function
+ */
 StorageService.prototype.downloadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
     cb = options;
@@ -100,6 +144,12 @@ StorageService.prototype.downloadStream = function (container, file, options, cb
   return this.client.download(options, cb);
 };
 
+/**
+ * List all files within the given container.
+ * @param {Object} container Container object.
+ * @param {Function} download 
+ * @param {Function} callback Callback function
+ */
 StorageService.prototype.getFiles = function (container, download, cb) {
   return this.client.getFiles(container, download, function (err, files) {
     if (err) {