Fix API docs (#80)

* Fix API docs

* Replace some text removed from doc comments

* Fix connector docs

* Fix parameterized sql docs

* Fix sql docs

docs/sql-connector.md

@@ -1,7 +1,6 @@
 Use the loopback-connector module to build a LoopBack connector to back-end data sources
 such as databases or web services.  There are many existing connectors for the most popular data sources; see:
-- [Database connectors](http://docs.strongloop.com/display/LB/Database+connectors) (for example, MongoDB, MySQL, Oracle).
-- [Non-database connectors](http://docs.strongloop.com/display/LB/Non-database+connectors) (for example, REST, SOAP).
-
-To build a new data source connector that doesn't yet exist, please see [Building a connector for a relational database](http://docs.strongloop.com/display/LB/Building+a+connector+for+a+relational+database).
+- [Database connectors](http://loopback.io/doc/en/lb3/Database-connectors.html) (for example, MongoDB, MySQL, Oracle).
+- [Other connectors](http://loopback.io/doc/en/lb3/Other-connectors.html) (for example, REST, SOAP).
 
+To build a new data source connector that doesn't yet exist, see [Building a connector](https://loopback.io/doc/en/lb3/Building-a-connector.html).

lib/connector.js

@@ -13,7 +13,7 @@ module.exports = Connector;
 /**
  * Base class for LoopBack connector. This is more a collection of useful
  * methods for connectors than a super class
- * @constructor
+ * @class
  */
 function Connector(name, settings) {
   this._models = {};
@@ -22,6 +22,7 @@ function Connector(name, settings) {
 }
 
 /**
+ * @private
  * Set the relational property to indicate the backend is a relational DB
  * @type {boolean}
  */
@@ -46,7 +47,7 @@ Connector.prototype.getTypes = function() {
 
 /**
  * Get the default data type for ID
- * @param prop Property definition
+ * @param {Object} prop Property definition
  * @returns {Function} The default type for ID
  */
 Connector.prototype.getDefaultIdType = function(prop) {
@@ -57,7 +58,7 @@ Connector.prototype.getDefaultIdType = function(prop) {
 /**
  * Generate random id.  Each data source model must override this method.
  * @param {String} modelName Model name
- * @returns {<model dependent>} Data type varies from model to model,
+ * @returns {*} Data type varies from model to model,
  */
 
 Connector.prototype.generateUniqueId = function(modelName) {
@@ -92,7 +93,7 @@ Connector.prototype.getMetadata = function() {
 /**
  * Execute a command with given parameters
  * @param {String|Object} command The command such as SQL
- * @param {*[]} [params] An array of parameter values
+ * @param {Array} [params] An array of parameter values
  * @param {Object} [options] Options object
  * @param {Function} [callback] The callback function
  */
@@ -163,7 +164,7 @@ Connector.prototype.idName = function(model) {
 /**
  * Get the id property names
  * @param {String} model The model name
- * @returns {[String]} The id property names
+ * @returns {String[]} The id property names
  */
 Connector.prototype.idNames = function(model) {
   return this.getDataSource(model).idNames(model);
@@ -292,4 +293,3 @@ Connector.defineAliases = function(cls, methodOrPropertyName, aliases) {
  * `command()` and `query()` are aliases to `execute()`
  */
 Connector.defineAliases(Connector.prototype, 'execute', ['command', 'query']);
-

lib/parameterized-sql.js

@@ -14,10 +14,10 @@ module.exports = ParameterizedSQL;
  * @param {String|Object} sql The SQL clause. If the value is a string, treat
  * it as the template using `?` as the placeholder, for example, `(?,?)`. If
  * the value is an object, treat it as {sql: '...', params: [...]}
- * @param {*[]} params An array of parameter values. The length should match the
+ * @param {Array} params An array of parameter values. The length should match the
  * number of placeholders in the template
  * @returns {ParameterizedSQL} A new instance of ParameterizedSQL
- * @constructor
+ * @class
  */
 function ParameterizedSQL(sql, params) {
   if (!(this instanceof ParameterizedSQL)) {
@@ -104,4 +104,3 @@ ParameterizedSQL.join = function(sqls, separator) {
 };
 
 ParameterizedSQL.PLACEHOLDER = PLACEHOLDER;
-

lib/sql.js

@@ -40,6 +40,7 @@ var PLACEHOLDER = SQLConnector.PLACEHOLDER = ParameterizedSQL.PLACEHOLDER;
 SQLConnector.Transaction = Transaction;
 
 /**
+ * @private
  * Set the relational property to indicate the backend is a relational DB
  * @type {boolean}
  */
@@ -592,7 +593,7 @@ SQLConnector.prototype.buildInsert = function(model, data, options) {
  * Execute a SQL statement with given parameters.
  *
  * @param {String} sql The SQL statement
- * @param {*[]} [params] An array of parameter values
+ * @param {Array} An array of parameter values
  * @param {Object} [options] Options object
  * @param {Function} [callback] The callback function
  */
@@ -1047,13 +1048,14 @@ function(columnName, operator, columnValue, propertyValue) {
   return stmt;
 };
 
-/*!
+/**
+ * @private
  * @param model
  * @param where
  * @returns {ParameterizedSQL}
- * @private
  */
 SQLConnector.prototype._buildWhere = function(model, where) {
+  var columnValue, sqlExp;
   if (!where) {
     return new ParameterizedSQL('');
   }
@@ -1096,12 +1098,10 @@ SQLConnector.prototype._buildWhere = function(model, where) {
       debug('Unknown property %s is skipped for model %s', key, model);
       continue;
     }
-    /* eslint-disable one-var */
-    var columnName = self.columnEscaped(model, key);
+    // eslint-disable one-var
     var expression = where[key];
-    var columnValue;
-    var sqlExp;
-    /* eslint-enable one-var */
+    var columnName = self.columnEscaped(model, key);
+    // eslint-enable one-var
     if (expression === null || expression === undefined) {
       stmt.merge(columnName + ' IS NULL');
     } else if (expression && expression.constructor === Object) {
@@ -1140,8 +1140,7 @@ SQLConnector.prototype._buildWhere = function(model, where) {
       } else {
         columnValue = this.toColumnValue(p, expression);
       }
-      sqlExp = self.buildExpression(
-        columnName, operator, columnValue, p);
+      sqlExp = self.buildExpression(columnName, operator, columnValue, p);
       stmt.merge(sqlExp);
     } else {
       // The expression is the field value, not a condition
@@ -1363,7 +1362,7 @@ SQLConnector.prototype.buildColumnNames = function(model, filter) {
  * @param {String} model Model name
  * @param {Object} filter Filter object
  * @param {Object} options Options object
- * @returns {ParameterizedSQL} Statement object {sql: ..., params: [...]}
+ * @returns {ParameterizedSQL} Statement object {sql: ..., params: ...}
  */
 SQLConnector.prototype.buildSelect = function(model, filter, options) {
   if (!filter.order) {
@@ -1553,7 +1552,7 @@ SQLConnector.prototype.createTable = function(model, cb) {
 
 /**
  * Recreate the tables for the given models
- * @param {[String]|String} [models] A model name or an array of model names,
+ * @param {String|String[]} [models] A model name or an array of model names,
  * if not present, apply to all models defined in the connector
  * @param {Function} [cb] The callback function
  */
@@ -1734,7 +1733,7 @@ SQLConnector.prototype.getInsertedId = function(model, info) {
 /**
  * Execute a SQL statement with given parameters
  * @param {String} sql The SQL statement
- * @param {*[]} [params] An array of parameter values
+ * @param {Array} [params] An array of parameter values
  * @param {Object} [options] Options object
  * @param {Function} [callback] The callback function
  */