Update jsdocs

docs.json

@@ -2,7 +2,7 @@
   "content": [
     { "title": "LoopBack Storage Service", "depth": 2 },
     "lib/storage-service.js",
-    { "title": "Storage Handler API", "depth": 3 },
+    { "title": "LoopBack Storage Connector", "depth": 2 },
-    "lib/storage-handler.js"
+    "lib/storage-connector.js"
   ]
 }

lib/providers/filesystem/index.js

@@ -190,10 +190,10 @@ FileSystemProvider.prototype.download = function (options, cb) {
   }
 };
 
-FileSystemProvider.prototype.getFiles = function (container, download, cb) {
+FileSystemProvider.prototype.getFiles = function (container, options, cb) {
-  if (typeof download === 'function' && !(download instanceof RegExp)) {
+  if (typeof options === 'function' && !(options instanceof RegExp)) {
-    cb = download;
+    cb = options;
-    download = false;
+    options = false;
   }
   var self = this;
   if (!validateName(container, cb)) return;

lib/storage-connector.js

@@ -1,8 +1,10 @@
 var StorageService = require('./storage-service');
 /**
- * Export the initialize method to Loopback data
+ * Initialize the storage service as a connector for LoopBack data sources
- * @param dataSource
+ * @param {DataSource} dataSource DataSource instance
- * @param callback
+ * @prop {Object} settings Connector settings
+ * @callback {Function} callback Callback function
+ * @param {String|Object} err Error string or object
  */
 exports.initialize = function (dataSource, callback) {
   var settings = dataSource.settings || {};

lib/storage-service.js

@@ -8,7 +8,7 @@ module.exports = StorageService;
 /**
  * Storage service constructor.  Properties of options object depend on the storage service provider.
  *
- * @options {Object} options The options to create a provider; see below.
+ * @options {Object} options Options to create a provider; see below.
  * @prop {String} provider Storage service provider. Must be one of:
  * <ul><li>'filesystem' - local file system.</li>
  * <li>'amazon'</li>
@@ -31,32 +31,14 @@ function StorageService(options) {
 
 function map(obj) {
   return obj;
-  /*
-   if (!obj || typeof obj !== 'object') {
-   return obj;
-   }
-   var data = {};
-   for (var i in obj) {
-   if (obj.hasOwnProperty(i) && typeof obj[i] !== 'function'
-   && typeof obj[i] !== 'object') {
-   if (i === 'newListener' || i === 'delimiter' || i === 'wildcard') {
-   // Skip properties from the base class
-   continue;
-   }
-   data[i] = obj[i];
-   }
-   }
-   return data;
-   */
 }
 
 /**
  * List all storage service containers.
- * @callback {Function} callback Callback function. See below.
+ * @callback {Function} callback Callback function
- * @param err {String} Error message
+ * @param {Object|String} err Error string or object
- * @param containers {Object} object holding all containers.
+ * @param {Object[]} containers An array of container metadata objects
  */
-
 StorageService.prototype.getContainers = function (cb) {
   this.client.getContainers(function (err, containers) {
     if (err) {
@@ -70,20 +52,13 @@ StorageService.prototype.getContainers = function (cb) {
 };
 
 /**
- * Create a new storage service container.  Other option properties depend on the provider.
+ * Create a new storage service container.
  *
- * @options {Object} options The options to create a provider; see below.
+ * @options {Object} options Options to create a container. Option properties depend on the provider.
- * @prop {String} provider Storage service provider. Must be one of:
+ * @prop {String} name Container name
- * <ul><li>'filesystem' - local file system.</li>
+ * @callback {Function} cb Callback function
- * <li>'amazon'</li>
+ * @param {Object|String} err Error string or object
- * <li>'rackspace'</li>
+ * @param {Object} container Container metadata object
- * <li>'azure'</li>
- * <li>'openstack'</li>
- * </ul>
- *
- * Other supported values depend on the provider.
- * See the [documentation](http://docs.strongloop.com/display/DOC/Storage+service) for more information.
- * @callback {Function} callback Callback function.
  */
 
 StorageService.prototype.createContainer = function (options, cb) {
@@ -99,17 +74,20 @@ StorageService.prototype.createContainer = function (options, cb) {
 
 /**
  * Destroy an existing storage service container.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
  * @callback {Function} callback Callback function.
+ * @param {Object|String} err Error string or object
  */
 StorageService.prototype.destroyContainer = function (container, cb) {
   return this.client.destroyContainer(container, cb);
 };
 
 /**
- * Look up a container by name.
+ * Look up a container metadata object by name.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
  * @callback {Function} callback Callback function.
+ * @param {Object|String} err Error string or object
+ * @param {Object} container Container metadata object
  */
 StorageService.prototype.getContainer = function (container, cb) {
   return this.client.getContainer(container, function (err, container) {
@@ -119,11 +97,12 @@ StorageService.prototype.getContainer = function (container, cb) {
 
 /**
  * Get the stream for uploading
- * @param {Object} container Container object.
+ * @param {String} container Container name
- * @param {String} file  <!-- IS THIS PATH TO A FILE OR FILE OBJ? -->
+ * @param {String} file  File name
- * @options options See below.
+ * @options {Object} [options] Options for uploading
- * @prop TBD
  * @callback callback Callback function
+ * @param {String|Object} err Error string or object
+ * @returns {Stream} Stream for uploading
  */
 StorageService.prototype.uploadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
@@ -143,11 +122,12 @@ StorageService.prototype.uploadStream = function (container, file, options, cb)
 
 /**
  * Get the stream for downloading.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {String} file Path to file.
+ * @param {String} file File name.
- * @options {Object} options See below.
+ * @options {Object} options Options for downloading
- * @prop TBD <!-- What are the options? -->
+ * @callback {Function} callback Callback function
- * @param {Function} callback Callback function
+ * @param {String|Object} err Error string or object
+ * @returns {Stream} Stream for downloading
  */
 StorageService.prototype.downloadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
@@ -167,12 +147,14 @@ StorageService.prototype.downloadStream = function (container, file, options, cb
 
 /**
  * List all files within the given container.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {Function} download <!-- What is this? -->
+ * @param {Object} [options] Options for download
- * @callback {Function} callback Callback function
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ * @param {Object[]} files An array of file metadata objects
  */
-StorageService.prototype.getFiles = function (container, download, cb) {
+StorageService.prototype.getFiles = function (container, options, cb) {
-  return this.client.getFiles(container, download, function (err, files) {
+  return this.client.getFiles(container, options, function (err, files) {
     if (err) {
       cb(err, files);
     } else {
@@ -183,20 +165,48 @@ StorageService.prototype.getFiles = function (container, download, cb) {
   });
 };
 
+/**
+ * Look up the metadata object for a file by name
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ * @param {Object} file File metadata object
+ */
 StorageService.prototype.getFile = function (container, file, cb) {
   return this.client.getFile(container, file, function (err, f) {
     return cb(err, map(f));
   });
 };
 
+/**
+ * Remove an existing file
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ */
 StorageService.prototype.removeFile = function (container, file, cb) {
   return this.client.removeFile(container, file, cb);
 };
 
+/*!
+ * Upload middleware for the HTTP request/response
+ * @param {Request} req Request object
+ * @param {Response} res Response object
+ * @param {Function} cb Callback function
+ */
 StorageService.prototype.upload = function (req, res, cb) {
   return handler.upload(this.client, req, res, req.params.container, cb);
 };
 
+/*!
+ * Download middleware
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @param {Response} res HTTP response
+ * @param {Function} cb Callback function
+ */
 StorageService.prototype.download = function (container, file, res, cb) {
   return handler.download(this.client, null, res, container, file, cb);
 };