[ci skip] Api ref for errors

docs/markdox.js

@@ -148,6 +148,7 @@ if (program.file) {
   files = [{file: program.file, output: 'tmp'}];
 } else {
   files = [
+    {file:'lib/errors.js', output: 'API-Reference-Errors'},
     {file:'lib/sequelize.js', output: 'API-Reference-Sequelize'},
     {file:'lib/instance.js', output: 'API-Reference-Instance'},
     {file:'lib/model.js', output: 'API-Reference-Model'},

lib/errors.js

 'use strict';
 
 /**
+ * Sequelize provides a host of custom error classes, to allow you to do easier debugging. All of these errors are exposed on the sequelize object and the sequelize constructor.
+ * All sequelize errors inherit from the base JS error object.
+ *
  * @fileOverview The Error Objects produced by Sequelize.
+ * @class Errors
  */
 
 var util = require('util');
@@ -11,6 +15,7 @@ var error = module.exports = {};
  * The Base Error all Sequelize Errors inherit from.
  *
  * @constructor
+ * @alias Error
  */
 error.BaseError = function() {
   var tmp = Error.apply(this, arguments);
@@ -23,7 +28,8 @@ util.inherits(error.BaseError, Error);
 
 
 /**
- * Validation Error
+ * Validation Error. Thrown when the sequelize validation has failed. The error contains an `errors` property,
+ * which is an array with 1 or more ValidationErrorItems, one for each validation that failed.
  *
  * @param {string} message Error message
  * @param {Array} [errors] Array of ValidationErrorItem objects describing the validation errors
@@ -37,7 +43,7 @@ error.ValidationError = function(message, errors) {
 util.inherits(error.ValidationError, error.BaseError);
 
 /**
- * Gets all validation error items for the path specified.
+ * Gets all validation error items for the path / field specified.
  *
  * @param {string} path The path to be checked for error items
  * @returns {Array} Validation error items for the specified path
@@ -52,8 +58,15 @@ error.ValidationError.prototype.get = function(path) {
 };
 
 /**
+ * An array of ValidationErrorItems
+ * @property errors
+ * @name errors
+ */
+error.ValidationError.prototype.errors;
+
+/**
  * Validation Error Item
- * Instances of this class are included in the ValidationError errors property.
+ * Instances of this class are included in the `ValidationError.errors` property.
  *
  * @param {string} message An error message
  * @param {string} type The type of the validation error

lib/instance.js

@@ -412,7 +412,7 @@ module.exports = (function() {
    * @param {Boolean} [options.silent=false] If true, the updatedAt timestamp will not be updated.
    * @param {Transaction} [options.transaction]
    *
-   * @return {Promise<this>}
+   * @return {Promise<this|Errors.ValidationError>}
    */
   Instance.prototype.save = function(fieldsOrOptions, options) {
     if (fieldsOrOptions instanceof Array) {
@@ -637,7 +637,7 @@ module.exports = (function() {
    * @param {Array} [options.skip] An array of strings. All properties that are in this array will not be validated
    * @see {InstanceValidator}
    *
-   * @return {Promise<undefined|Error}
+   * @return {Promise<undefined|Errors.ValidationError}
    */
   Instance.prototype.validate = function(options) {
     return new InstanceValidator(this, options).validate();

lib/sequelize.js

@@ -226,6 +226,7 @@ module.exports = (function() {
   /**
    * A general error class
    * @property Error
+   * @see {Errors#BaseError}
    */
   Sequelize.prototype.Error = Sequelize.Error =
     sequelizeErrors.BaseError;
@@ -233,6 +234,7 @@ module.exports = (function() {
   /**
    * Emitted when a validation fails
    * @property ValidationError
+   * @see {Errors#ValidationError}
    */
   Sequelize.prototype.ValidationError = Sequelize.ValidationError =
     sequelizeErrors.ValidationError;
@@ -240,6 +242,7 @@ module.exports = (function() {
   /**
    * Describes a validation error on an instance path
    * @property ValidationErrorItem
+   * @see {Errors#ValidationErrorItem}
    */
   Sequelize.prototype.ValidationErrorItem = Sequelize.ValidationErrorItem =
     sequelizeErrors.ValidationErrorItem;