refactoring documentation.

Author: vitaly-t

lib/helpers/columnSet.js

@@ -481,26 +481,30 @@ function ColumnSet(columns, options) {
      * Prepares a source object to be formatted, by cloning it and applying the rules
      * as set by the columns configuration.
      *
-     * This method is primarily for internal use.
+     * This method is primarily for internal use, and as such it does not validate
+     * its input parameters.
+     *
+     * @param {object} source
+     * The source object to be prepared, if required.
      *
-     * @param {object} obj
-     * Source object to be prepared.
+     * It must be a non-`null` object, which the method does not validate, as it is
+     * intended primarily for internal use by the library.
      *
      * @returns {object}
      * When the object needs to be prepared, the method returns a clone of the source object,
      * with all properties and values set according to the columns configuration.
      *
      * When the object does not need to be prepared, the original object is returned.
      */
-    this.prepare = function (obj) {
+    this.prepare = function (source) {
         if (isSimple) {
-            return obj; // a simple ColumnSet requires no object preparation;
+            return source; // a simple ColumnSet requires no object preparation;
         }
         var target = {};
         $arr.forEach(this.columns, function (c) {
-            var a = colDesc(c, obj);
+            var a = colDesc(c, source);
             if (c.init) {
-                target[a.name] = c.init.call(obj, a);
+                target[a.name] = c.init.call(source, a);
             } else {
                 if (a.exists || 'def' in c) {
                     target[a.name] = a.value;

lib/queryFile.js

@@ -31,45 +31,8 @@ var $npm = {
  *
  * If there is any problem reading the file, it will be reported when executing the query.
  *
- * @param {object} [options]
- * A set of configuration options.
- *
- * @param {boolean} [options.debug]
- * When in debug mode, the query file is checked for its last modification time on every query request,
- * so if it changes, the file is read afresh.
- *
- * The default for this property is `true` when `NODE_ENV` = `development`,
- * or `false` otherwise.
- *
- * @param {boolean|string} [options.minify=false]
- * Parses and minifies the SQL using $[pg-minify]:
- * - `false` - do not use $[pg-minify]
- * - `true` - use $[pg-minify] to parse and minify SQL
- * - `'after'` - use $[pg-minify] after applying static formatting parameters
- *   (option `params`), as opposed to before it (default)
- *
- * If option `compress` is set, then the default for `minify` is `true`.
- *
- * Failure to parse SQL will result in $[SQLParsingError].
- *
- * @param {boolean} [options.compress=false]
- * Sets option `compress` as supported by $[pg-minify], to uglify the SQL:
- * - `false` - no compression to be applied, keep minimum spaces for easier read
- * - `true` - remove all unnecessary spaces from SQL
- *
- * This option has no meaning, if `minify` is explicitly set to `false`. However, if `minify` is not
- * specified and `compress` is specified as `true`, then `minify` defaults to `true`.
- *
- * @param {array|object|value} [options.params]
- * Static formatting parameters to be applied to the SQL, using the same method {@link formatting.format as.format},
- * but with option `partial` = `true`.
- *
- * Most of the time query formatting is fully dynamic, and applied just before executing the query.
- * In some cases though you may need to pre-format SQL with static values. Examples of it can be a
- * schema name, or a configurable table name.
- *
- * This option makes two-step SQL formatting easy: you can pre-format the SQL initially, and then
- * apply the second-step dynamic formatting when executing the query.
+ * @param {QueryFile.Options} [options]
+ * Set of configuration options, as documented by {@link QueryFile.Options}.
  *
  * @returns {QueryFile}
  *
@@ -229,7 +192,7 @@ function QueryFile(file, options) {
 
     /**
      * @name QueryFile#query
-     * @type string
+     * @type {string}
      * @default undefined
      * @readonly
      * @summary Prepared query string.
@@ -262,7 +225,7 @@ function QueryFile(file, options) {
 
     /**
      * @name QueryFile#file
-     * @type string
+     * @type {string}
      * @readonly
      * @description
      * File name that was passed into the constructor.
@@ -277,7 +240,7 @@ function QueryFile(file, options) {
 
     /**
      * @name QueryFile#options
-     * @type object
+     * @type {QueryFile.Options}
      * @readonly
      * @description
      * Set of options, as configured during the object's construction.
@@ -328,3 +291,47 @@ QueryFile.prototype.inspect = function () {
 };
 
 module.exports = QueryFile;
+
+/**
+ * @typedef QueryFile.Options
+ * @description
+ * A set of configuration options as passed into the {@link QueryFile} constructor.
+ *
+ * @property {boolean} debug
+ * When in debug mode, the query file is checked for its last modification time on every query request,
+ * so if it changes, the file is read afresh.
+ *
+ * The default for this property is `true` when `NODE_ENV` = `development`,
+ * or `false` otherwise.
+ *
+ * @property {boolean|string} minify=false
+ * Parses and minifies the SQL using $[pg-minify]:
+ * - `false` - do not use $[pg-minify]
+ * - `true` - use $[pg-minify] to parse and minify SQL
+ * - `'after'` - use $[pg-minify] after applying static formatting parameters
+ *   (option `params`), as opposed to before it (default)
+ *
+ * If option `compress` is set, then the default for `minify` is `true`.
+ *
+ * Failure to parse SQL will result in $[SQLParsingError].
+ *
+ * @property {boolean} compress=false
+ * Sets option `compress` as supported by $[pg-minify], to uglify the SQL:
+ * - `false` - no compression to be applied, keep minimum spaces for easier read
+ * - `true` - remove all unnecessary spaces from SQL
+ *
+ * This option has no meaning, if `minify` is explicitly set to `false`. However, if `minify` is not
+ * specified and `compress` is specified as `true`, then `minify` defaults to `true`.
+ *
+ * @property {array|object|value} params
+ *
+ * Static formatting parameters to be applied to the SQL, using the same method {@link formatting.format as.format},
+ * but with option `partial` = `true`.
+ *
+ * Most of the time query formatting is fully dynamic, and applied just before executing the query.
+ * In some cases though you may need to pre-format SQL with static values. Examples of it can be a
+ * schema name, or a configurable table name.
+ *
+ * This option makes two-step SQL formatting easy: you can pre-format the SQL initially, and then
+ * apply the second-step dynamic formatting when executing the query.
+ */