[ci skip] Add API docs and changelog entry for nest option to .query

changelog.md

@@ -3,6 +3,7 @@ Notice: All 1.7.x changes are present in 2.0.x aswell
 # Next
 # Next
 - [FEATURE] Added to option of setting a timezone offset in the sequelize constructor (`timezone` option). This timezone is used when initializing a connection (using `SET TIME ZONE` or equivalent), and when converting a timestamp string from the DB to a JS date with mysql (postgres stores the timezone, so for postgres we rely on what's in the DB).
 - [FEATURE] Added to option of setting a timezone offset in the sequelize constructor (`timezone` option). This timezone is used when initializing a connection (using `SET TIME ZONE` or equivalent), and when converting a timestamp string from the DB to a JS date with mysql (postgres stores the timezone, so for postgres we rely on what's in the DB).
 - [FEATURE] Allow setting plural and singular name on the model (`options.name` in `sequelize.define`) and in associations (`options.as`) to circumvent issues with weird pluralization.
 - [FEATURE] Allow setting plural and singular name on the model (`options.name` in `sequelize.define`) and in associations (`options.as`) to circumvent issues with weird pluralization.
+- [BUG] Hid `dottie.transform` on raw queries behind a flag (`nest`) [#2064](https://github.com/sequelize/sequelize/pull/2064)
 - [BUG] Fixed problems with transcation parameter being removed / not passed on in associations [#1789](https://github.com/sequelize/sequelize/issues/1789) and [#1968](https://github.com/sequelize/sequelize/issues/1968)
 - [BUG] Fixed problems with transcation parameter being removed / not passed on in associations [#1789](https://github.com/sequelize/sequelize/issues/1789) and [#1968](https://github.com/sequelize/sequelize/issues/1968)
 - [BUG] Fix problem with minConnections. [#2048](https://github.com/sequelize/sequelize/issues/2048)
 - [BUG] Fix problem with minConnections. [#2048](https://github.com/sequelize/sequelize/issues/2048)
 - [INTERNALS] Replaced lingo with inflection
 - [INTERNALS] Replaced lingo with inflection

lib/sequelize.js

@@ -467,13 +467,14 @@ module.exports = (function() {
    * If you do not provide other arguments than the SQL, raw will be assumed to the true, and sequelize will not try to do any formatting to the results of the query.
    * If you do not provide other arguments than the SQL, raw will be assumed to the true, and sequelize will not try to do any formatting to the results of the query.
    *
    *
    * @method query
    * @method query
-   * @param {String} sql
-   * @param {Model}  [callee] If callee is provided, the selected data will be used to build an instance of the DAO represented by the factory. Equivalent to calling Model.build with the values provided by the query.
-   * @param {Object}      [options={}] Query options.
-   * @param {Boolean}     [options.raw] If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
-   * @param {Transaction} [options.transaction=null] The transaction that the query should be executed under
-   * @param [String]      [options.type='SELECT'] The type of query you are executing. The query type affects how results are formatted before they are passed back. If no type is provided sequelize will try to guess the right type based on the sql, and fall back to SELECT. The type is a string, but `Sequelize.QueryTypes` is provided is convenience shortcuts. Current options are SELECT, BULKUPDATE and BULKDELETE
-   * @param {Object|Array} [replacements] Either an object of named parameter replacements in the format `:param` or an array of unnamed replacements to replace `?` in your SQL.
+   * @param {String}        sql
+   * @param {Model}         [callee] If callee is provided, the selected data will be used to build an instance of the DAO represented by the factory. Equivalent to calling Model.build with the values provided by the query.
+   * @param {Object}        [options={}] Query options.
+   * @param {Boolean}       [options.raw] If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
+   * @param {Transaction}   [options.transaction=null] The transaction that the query should be executed under
+   * @param {String}        [options.type='SELECT'] The type of query you are executing. The query type affects how results are formatted before they are passed back. If no type is provided sequelize will try to guess the right type based on the sql, and fall back to SELECT. The type is a string, but `Sequelize.QueryTypes` is provided is convenience shortcuts. Current options are SELECT, BULKUPDATE and BULKDELETE
+   * @param {Boolean}       [options.nest=false] If true, transforms objects with `.` separated property names into nested objects using [dottie.js](https://github.com/mickhansen/dottie.js). For example { 'user.username': 'john' } becomes { user: { username: 'john' }}
+   * @param {Object|Array}  [replacements] Either an object of named parameter replacements in the format `:param` or an array of unnamed replacements to replace `?` in your SQL.
    * @return {Promise}
    * @return {Promise}
    *
    *
    * @see {Model#build} for more information about callee.
    * @see {Model#build} for more information about callee.