Updated README.md and clarified comments.

Author: nareshbhatia

README.md

@@ -1,11 +1,11 @@
 # JoinJS
 
-JoinJS is a JavaScript library to map complex database joins to nested objects. It's a simpler alternative to a full-blown Object-Relation Mapper (ORM), but gives you direct control over your database interactions.
+JoinJS is a JavaScript library to map complex database joins to nested objects. It's a simpler alternative to a full-blown Object-Relation Mapper (ORM), and gives you direct control over your database interactions.
 
 ## Motivation
-ORMs generally introduce a thick layer of abstraction between objects and database tables. This usually hinders rather than helps developer productivity. In complex use cases, it is difficult enough to devise efficient queries, but with ORMs, you also have to *teach* them to generate the same query. It takes extra time to do this and you may not be able to produce the same query. In the worst case scenario, the ORM may hit the database multiple times for something that you were able to do in a single query.
+ORMs generally introduce a thick layer of abstraction between objects and database tables. This usually hinders, rather than helps, developer productivity. In complex use cases, it is difficult enough to devise efficient queries, but with ORMs you also have to *teach* them to generate the same query. It takes extra time to do this and you may not be able to produce the same query. In the worst case scenario, the ORM may hit the database multiple times for something that you were able to do in a single query.
 
-JoinJS takes a much simple and straightforward approach inspired by a Java library called [MyBatis](http://mybatis.github.io/mybatis-3/). You can use any database driver or query builder (such as [Kenx.js](http://knexjs.org/)) to query your database, however you use JoinJS to convert the returned results to a hierarchy of nested objects.
+JoinJS takes a much simpler and straightforward approach inspired by a Java library called [MyBatis](http://mybatis.github.io/mybatis-3/). You can use any database driver or query builder (such as [Knex.js](http://knexjs.org/)) to query your database, however you use JoinJS to convert the returned results to a hierarchy of nested objects.
 
 ## Example
 Suppose you have a one-to-many relationship between a `Team` and its `Players`. You want to retrieve all teams along with their players. Here's the query for to do this:
@@ -48,8 +48,8 @@ You can use JoinJS to convert this result set in to an array of teams with neste
         id: 2,
         name: 'New York Jets'
         players: [
-            { id: 1, name: 'Tom Brady'      },
-            { id: 2, name: 'Rob Gronkowski' }
+            { id: 3, name: 'Geno Smith'     },
+            { id: 4, name: 'Darrelle Revis' }
         ]
     }
 ]
@@ -96,11 +96,11 @@ $ npm install join-js
 ## Documentation
 
 ### ResultMap
-ResulpMaps are used to teach JoinJS how to map database results to objects. Each result map focuses on a single object. The properties of a ResultMap are described below. You can find several examples in the [test suite](https://github.com/archfirst/joinjs/tree/master/test).
+ResultMaps are used to teach JoinJS how to map database results to objects. Each result map focuses on a single object. The properties of a ResultMap are described below. You can find several examples in the [test suite](https://github.com/archfirst/joinjs/tree/master/test).
 
 - `mapId {String}` - A unique identifier for the map
 
-- `createNew {function} (optional)` - A function that returns a blank new instance of the mapped object. Use this property to construct a custom object instead of generic JavaScript `Object`.
+- `createNew {function} (optional)` - A function that returns a blank new instance of the mapped object. Use this property to construct a custom object instead of a generic JavaScript `Object`.
 
 - `idProperty {Object} (optional)` - specifies the name of the id property in the mapped object and in the result set. Default is `{name: 'id', column: 'id'}`.
     - `name` - property that identifies the mapped object
@@ -112,12 +112,12 @@ ResulpMaps are used to teach JoinJS how to map database results to objects. Each
 
 - `associations {Array} (optional)` - mappings for associations to other objects. Each mapping contains:
     - `name` - property name of the association in the mapped object
-    - `mapId` - identifier of the map for the associated object
+    - `mapId` - identifier of the result map of the associated object
     - `columnPrefix (optional)` - a prefix to apply to every column of the associated object. Default is an empty string.
 
 - `collections {Array} (optional)` - mappings for collections of other objects. Each mapping contains:
     - `name` - property name of the collection in the mapped object
-    - `mapId` - identifier of the map for the associated objects
+    - `mapId` - identifier of the result map of the associated objects
     - `columnPrefix (optional)` - a prefix to apply to every column of the associated object. Default is an empty string.
 
 ### API
@@ -138,11 +138,11 @@ Returns an array of mapped objects.
 
 #### mapOne(resultSet, maps, mapId, columnPrefix, isRequired)
 
-This is a convenience method that maps a resultSet to a single object.
+This is a convenience method that maps a resultSet to a single object. It is used when your select query is expected to return only one result (e.g. `SELECT * FROM table WHERE id = 1234`).
 
 - `resultSet {Array}` - an array of database results
 - `maps {Array}` - an array of result maps
-- `mapId {String}` - mapId of the top-level objects in the resultSet
+- `mapId {String}` - mapId of the top-level object in the resultSet
 - `columnPrefix {String} (optional)` - prefix that should be applied to the column names of the top-level objects
 - `isRequired {boolean} (optional)` - is it required to have a mapped object as a return value? Default is `true`.
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "join-js",
   "description": "A library to map complex database joins to nested objects.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Naresh Bhatia",
   "license": "MIT",
   "homepage": "https://github.com/archfirst/joinjs",

src/index.js

@@ -33,9 +33,9 @@ function map(resultSet, maps, mapId, columnPrefix) {
  *
  * @param {Array} resultSet - an array of database results
  * @param {Array} maps - an array of result maps
- * @param {String} mapId - mapId of the top-level objects in the resultSet
- * @param {String} [columnPrefix] - prefix that should be applied to the column names of the top-level objects
- * @param {boolean} [isRequired] - is a mapped object required to be returned, default is true
+ * @param {String} mapId - mapId of the top-level object in the resultSet
+ * @param {String} [columnPrefix] - prefix that should be applied to the column names of the top-level object
+ * @param {boolean} [isRequired] - is it required to have a mapped object as a return value? Default is true.
  * @returns {Object} one mapped object or null
  * @throws {NotFoundError} if object is not found and isRequired is true
  */