Updates to JSDoc comments for API doc

lib/dao.js

@@ -1,9 +1,9 @@
-/**
+/*!
  * Module exports class Model
  */
 module.exports = DataAccessObject;
 
-/**
+/*!
  * Module dependencies
  */
 var jutil = require('./jutil');
@@ -19,15 +19,14 @@ var fieldsToArray = utils.fieldsToArray;
 var removeUndefined = utils.removeUndefined;
 
 /**
- * DAO class - base class for all persist objects
- * provides **common API** to access any database connector.
- * This class describes only abstract behavior layer, refer to `lib/connectors/*.js`
- * to learn more about specific connector implementations
+ * Base class for all persistent objects.
+ * Provides a common API to access any database connector.
+ * This class describes only abstract behavior.  Refer to the specific connector (`lib/connectors/*.js`) for details.
  *
- * `DataAccessObject` mixes `Inclusion` classes methods
+ * `DataAccessObject` mixes `Inclusion` classes methods.
  *
- * @constructor
- * @param {Object} data - initial object data
+ * @class DataAccessObject
+ * @param {Object} data Initial object data
  */
 function DataAccessObject() {
   if (DataAccessObject._mixins) {
@@ -71,14 +70,15 @@ DataAccessObject._forDB = function (data) {
 };
 
 /**
- * Create new instance of Model class, saved in database
- *
- * @param data [optional]
- * @param callback(err, obj)
- * callback called with arguments:
+ * Create new instance of Model class, saved in database.
+ * The callback function is called with arguments:
  *
  *   - err (null or Error)
  *   - instance (null or Model)
+ *
+ * @param data {Object} Optional data object
+ * @param callback {Function} Callback function 
+
  */
 DataAccessObject.create = function (data, callback) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -208,9 +208,9 @@ function stillConnecting(dataSource, obj, args) {
 }
 
 /**
- * Update or insert a model instance
+ * Update or insert a model instance.
  * @param {Object} data The model instance data
- * @param {Function} [callback] The callback function
+ * @param {Function} callback The callback function (optional).
  */
 DataAccessObject.upsert = DataAccessObject.updateOrCreate = function upsert(data, callback) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -254,9 +254,9 @@ setRemoting(DataAccessObject.upsert, {
  * Find one record, same as `all`, limited by 1 and return object, not collection,
  * if not found, create using data provided as second argument
  *
- * @param {Object} query - search conditions: {where: {test: 'me'}}.
- * @param {Object} data - object to create.
- * @param {Function} cb - callback called with (err, instance)
+ * @param {Object} query Search conditions: {where: {test: 'me'}}.
+ * @param {Object} data Object to create.
+ * @param {Function} cb Callback called with (err, instance)
  */
 DataAccessObject.findOrCreate = function findOrCreate(query, data, callback) {
   if (query === undefined) {
@@ -282,8 +282,8 @@ DataAccessObject.findOrCreate = function findOrCreate(query, data, callback) {
 /**
  * Check whether a model instance exists in database
  *
- * @param {id} id - identifier of object (primary key value)
- * @param {Function} cb - callbacl called with (err, exists: Bool)
+ * @param {id} id Identifier of object (primary key value)
+ * @param {Function} cb Callback function called with (err, exists: Bool)
  */
 DataAccessObject.exists = function exists(id, cb) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -306,8 +306,8 @@ setRemoting(DataAccessObject.exists, {
 /**
  * Find object by id
  *
- * @param {*} id - primary key value
- * @param {Function} cb - callback called with (err, instance)
+ * @param {*} id Primary key value
+ * @param {Function} cb Callback called with (err, instance)
  */
 DataAccessObject.findById = function find(id, cb) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -458,20 +458,16 @@ DataAccessObject._coerce = function (where) {
 
 /**
  * Find all instances of Model, matched by query
- * make sure you have marked as `index: true` fields for filter or sort
- *
- * @param {Object} params (optional)
- *
+ * make sure you have marked as `index: true` fields for filter or sort.
+ * The params object:
  * - where: Object `{ key: val, key2: {gt: 'val2'}}`
- * - include: String, Object or Array. See DataAccessObject.include documentation.
+ * - include: String, Object or Array. See `DataAccessObject.include()`.
  * - order: String
  * - limit: Number
  * - skip: Number
- *
- * @param {Function} callback (required) called with arguments:
- *
- * - err (null or Error)
- * - Array of instances
+ * 
+ * @param {Object} params (optional)
+ * @param {Function} callback (required) called with two arguments: err (null or Error), array of instances
  */
 
 DataAccessObject.find = function find(params, cb) {
@@ -598,8 +594,8 @@ setRemoting(DataAccessObject.find, {
 /**
  * Find one record, same as `all`, limited by 1 and return object, not collection
  *
- * @param {Object} params - search conditions: {where: {test: 'me'}}
- * @param {Function} cb - callback called with (err, instance)
+ * @param {Object} params Search conditions: {where: {test: 'me'}}
+ * @param {Function} cb Callback called with (err, instance)
  */
 DataAccessObject.findOne = function findOne(params, cb) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -626,7 +622,7 @@ setRemoting(DataAccessObject.findOne, {
 /**
  * Destroy all matching records
  * @param {Object} [where] An object that defines the criteria
- * @param {Function} [cb] - callback called with (err)
+ * @param {Function} [cb] Callback called with (err)
  */
 DataAccessObject.remove =
   DataAccessObject.deleteAll =
@@ -657,7 +653,7 @@ DataAccessObject.remove =
 /**
  * Destroy a record by id
  * @param {*} id The id value
- * @param {Function} cb - callback called with (err)
+ * @param {Function} cb Callback called with (err)
  */
 DataAccessObject.removeById =
   DataAccessObject.deleteById =
@@ -683,8 +679,8 @@ setRemoting(DataAccessObject.deleteById, {
 /**
  * Return count of matched records
  *
- * @param {Object} where - search conditions (optional)
- * @param {Function} cb - callback, called with (err, count)
+ * @param {Object} where Search conditions (optional)
+ * @param {Function} cb Callback, called with (err, count)
  */
 DataAccessObject.count = function (where, cb) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -797,7 +793,7 @@ DataAccessObject.prototype._adapter = function () {
 /**
  * Delete object from persistence
  *
- * @triggers `destroy` hook (async) before and after destroying object
+ * Triggers `destroy` hook (async) before and after destroying object
  */
 DataAccessObject.prototype.remove =
   DataAccessObject.prototype.delete =
@@ -825,9 +821,9 @@ DataAccessObject.prototype.remove =
  *
  * equals to `updateAttributes({name: value}, cb)
  *
- * @param {String} name - name of property
- * @param {Mixed} value - value of property
- * @param {Function} callback - callback called with (err, instance)
+ * @param {String} name Name of property
+ * @param {Mixed} value Value of property
+ * @param {Function} callback Callback function called with (err, instance)
  */
 DataAccessObject.prototype.updateAttribute = function updateAttribute(name, value, callback) {
   var data = {};
@@ -841,8 +837,8 @@ DataAccessObject.prototype.updateAttribute = function updateAttribute(name, valu
  * this method performs validation before updating
  *
  * @trigger `validation`, `save` and `update` hooks
- * @param {Object} data - data to update
- * @param {Function} callback - callback called with (err, instance)
+ * @param {Object} data Data to update
+ * @param {Function} callback Callback function called with (err, instance)
  */
 DataAccessObject.prototype.updateAttributes = function updateAttributes(data, cb) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -911,9 +907,8 @@ setRemoting(DataAccessObject.prototype.updateAttributes, {
 
 /**
  * Reload object from persistence
- *
- * @requires `id` member of `object` to be able to call `find`
- * @param {Function} callback - called with (err, instance) arguments
+ * Requires `id` member of `object` to be able to call `find`
+ * @param {Function} callback Called with (err, instance) arguments
  */
 DataAccessObject.prototype.reload = function reload(callback) {
   if (stillConnecting(this.getDataSource(), this, arguments)) return;
@@ -946,8 +941,8 @@ function defineReadonlyProp(obj, key, value) {
 
 var defineScope = require('./scope.js').defineScope;
 
-/**
- * Define scope
+/*!
+ * Define scope. N.B. Not clear if this needs to be exposed in API doc.
  */
 DataAccessObject.scope = function (name, filter, targetClass) {
   defineScope(this, targetClass || this, name, filter);