Merge pull request #1358 from strongloop/api-doc-2

Update api documents

Author: loay

lib/datasource.js

@@ -744,19 +744,19 @@ DataSource.prototype.mixin = function(ModelCtor) {
   });
 };
 
+/*! Method will be deprecated in LoopBack.next
+*/
 /**
- *
- * FIXME: Deprecation notice for 4.x?
  * See [ModelBuilder.getModel](http://apidocs.strongloop.com/loopback-datasource-juggler/#modelbuilder-prototype-getmodel)
  * for details.
  */
 DataSource.prototype.getModel = function(name, forceCreate) {
   return this.modelBuilder.getModel(name, forceCreate);
 };
 
+/*! Method will be deprecated in LoopBack.next
+*/
 /**
- * // FIXME: Make this a link to ModelBuilder.getModelDefinition's docs!
- * // FIXME: Deprecation notice for 4.x?
  * See ModelBuilder.getModelDefinition
  * See [ModelBuilder.getModelDefinition](http://apidocs.strongloop.com/loopback-datasource-juggler/#modelbuilder-prototype-getmodeldefinition)
  * for details.
@@ -765,6 +765,8 @@ DataSource.prototype.getModelDefinition = function(name) {
   return this.modelBuilder.getModelDefinition(name);
 };
 
+/*! Method will be deprecated in LoopBack.next
+*/
 /**
  * Get the data source types collection.
  * @returns {String[]} The data source type array.
@@ -773,7 +775,6 @@ DataSource.prototype.getModelDefinition = function(name) {
  *
  * Alternatively, ['rest'] would be a different type altogether, and would have
  * no subtype.
- * FIXME: Deprecation notice for 4.x?
  */
 DataSource.prototype.getTypes = function() {
   var getTypes = this.connector && this.connector.getTypes;
@@ -806,14 +807,15 @@ DataSource.prototype.supportTypes = function(types) {
   }
 };
 
+/*! In future versions, this will not maintain a strict 1:1 relationship between datasources and model classes
+* Moving forward, we will allow a model to be attached to a datasource. The model itself becomes a template.
+*/
 /**
  * Attach an existing model to a data source.
  * This will mixin all of the data access object functions (DAO) into your
  * modelClass definition.
  * @param {Function} modelClass The model constructor that will be enhanced by
  * DAO mixins.
- * FIXME: In future versions, this will not maintain a strict 1:1 relationship
- * between datasources and model classes.
  */
 
 DataSource.prototype.attach = function(modelClass) {
@@ -837,11 +839,12 @@ DataSource.prototype.attach = function(modelClass) {
   return modelClass;
 };
 
+/*! Method will be deprecated in LoopBack.next
+*/
 /**
  * Define a property with name `prop` on a target `model`. See
  * [Properties](./Model-definition-JSON-file.html#properties) for more information
  * regarding valid options for `params`.
- * FIXME: Deprecate for 4.0?
  * @param {String} model Name of model
  * @param {String} prop Name of property
  * @param {Property} params Property settings
@@ -1010,8 +1013,9 @@ DataSource.prototype.discoverModelDefinitions = function(options, cb) {
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
- * FIXME Deprecate/remove this for LB 4.0?
  * The synchronous version of discoverModelDefinitions.
  * @options {Object} options The options
  * @property {Boolean} all If true, discover all models; if false, discover only models owned by the current user.
@@ -1071,8 +1075,9 @@ DataSource.prototype.discoverModelProperties = function(modelName, options, cb)
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
- * FIXME: Deprecate this for LB 4.x?
  * The synchronous version of discoverModelProperties
  * @param {String} modelName The table/view name
  * @param {Object} options The options
@@ -1123,8 +1128,9 @@ DataSource.prototype.discoverPrimaryKeys = function(modelName, options, cb) {
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
- * FIXME: Obsolete?
  * The synchronous version of discoverPrimaryKeys
  * @param {String} modelName The model name
  * @options {Object} options The options
@@ -1182,8 +1188,9 @@ DataSource.prototype.discoverForeignKeys = function(modelName, options, cb) {
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
- * FIXME: Obsolete?
  * The synchronous version of discoverForeignKeys
  *
  * @param {String} modelName The model name
@@ -1242,8 +1249,9 @@ DataSource.prototype.discoverExportedForeignKeys = function(modelName, options,
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
- * FIXME: Obsolete?
  * The synchronous version of discoverExportedForeignKeys
  * @param {String} modelName The model name
  * @param {Object} options The options
@@ -1564,9 +1572,10 @@ DataSource.prototype.discoverSchemas = function(tableName, options, cb) {
   return cb.promise;
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
  * Discover schema from a given table/view synchronously
- * FIXME Obsolete?
  * @param {String} modelName The model name
  * @options {Object} [options] Options; see below.
  * @property {String} owner|schema Database owner or schema name.
@@ -1749,9 +1758,10 @@ DataSource.prototype.discoverAndBuildModels = function(modelName, options, cb) {
   });
 };
 
+/*! Method will be completely removed in LoopBack.next
+*/
 /**
  * Discover and build models from the given owner/modelName synchronously.
- * FIXME: Obsolete?
  * @param {String} modelName The model name.
  * @options {Object} [options] Options; see below.
  * @property {String} owner|schema Database owner or schema name.
@@ -1835,9 +1845,7 @@ DataSource.prototype.log = function(sql, t) {
 
 /**
  * Freeze dataSource. Behavior depends on connector
- * REVIEW: Raymond, can you give example of what behavior(s) are typically
- * expected here? I understand that it's connector-specific, but surely there's
- * a common goal here.
+ * To continuously add artifacts to datasource until it is frozen, but it is not really used in loopback.
  */
 DataSource.prototype.freeze = function freeze() {
   if (!this.connector) {
@@ -1988,10 +1996,10 @@ DataSource.prototype.defineForeignKey = function defineForeignKey(className, key
 
 /**
  * Close connection to the DataSource.
- * REVIEW: Why is this not Promisified like the connect function?
  * @param {Function} [cb] The callback function. Optional.
  */
 DataSource.prototype.disconnect = function disconnect(cb) {
+  cb = cb || utils.createPromiseCallback();
   var self = this;
   if (this.connected && (typeof this.connector.disconnect === 'function')) {
     this.connector.disconnect(function(err, result) {
@@ -2004,6 +2012,7 @@ DataSource.prototype.disconnect = function disconnect(cb) {
       cb && cb();
     });
   }
+  return cb.promise;
 };
 
 /**
@@ -2197,9 +2206,8 @@ DataSource.prototype.isRelational = function() {
 /**
  * Check if the data source is ready.
  * Returns a Boolean value.
- * REVIEW: What is "obj" supposed to represent?
- * @param {Object} obj  ?
- * @param {Object} args  ?
+ * @param {Object} obj  Deferred method call if the connector is not fully connected yet
+ * @param {Object} args  argument passing to method call.
  */
 DataSource.prototype.ready = function(obj, args) {
   var self = this;
@@ -2286,10 +2294,11 @@ DataSource.prototype.ping = function(cb) {
   }
 };
 
+/*! The hidden property call is too expensive so it is not used that much
+*/
 /**
  * Define a hidden property
- * REVIEW: Why is a hidden property not writable or enumerable? What
- * purpose does it serve?
+ * It is an utility to define a property to the Object with info flags
  * @param {Object} obj The property owner
  * @param {String} key The property name
  * @param {Mixed} value The default value