Docs review.

markdown/db/wrappers/mongo.md

@@ -3,9 +3,11 @@
 This package is a wrapper of [mgo](http://labix.org/mgo), a MongoDB driver by
 [Gustavo Niemeyer](http://labyx.org).
 
-## Installation
+## Usage example
 
-### Driver pre-requisites
+### 1. Get the wrapper
+
+Package pre-requisites:
 
 The [bazaar](http://bazaar.canonical.com/en/) version control system is required
 to install `mgo`.
@@ -14,45 +16,99 @@ to install `mgo`.
 # OSX
 brew install bzr
 
-# Debian based
+# Debian based distro.
 sudo aptitude install bzr
 
 # ArchLinux
 sudo pacman -S bzr
 ```
 
-### Downloading and installing
+Installing the package.
 
 ```sh
-go get menteslibres.net/gosexy/db/mongo
+go get -u menteslibres.net/gosexy/db
+go get -u menteslibres.net/gosexy/db/mongo
 ```
 
-## Usage
+### 1. Import the wrapper
 
-Import the `gosexy/db` and `gosexy/db/mongo` packages.
+Import both the `gosexy/db` and the `gosexy/db/mongo` packages. The driver
+package must be imported to the
+[blank identifier](http://golang.org/doc/effective_go.html#blank) as we are not
+going to use any of its methods directly.
 
 ```go
 import (
   "menteslibres.net/gosexy/db"
-	# Note that we are importing to the blank identifier.
+  // Note the underscore at the beginning
   _ "menteslibres.net/gosexy/db/mongo"
 )
 ```
 
-### Connecting to a MongoDB database
+### 3. Define how to connect to the database
+
+Use a `db.DataSource` variable to store the database settings.
 
 ```go
-sess, err := db.Open("mongo", db.DataSource{Host: "127.0.0.1", ...})
+var settings = db.DataSource{
+  Host:     "localhost",
+  Database: "test",
+}
+```
+
+### 3. Connect to the source.
+
+Use `db.Open()` to request a connection to the database and
+`db.Database.Close()` to close it.
+
+```go
+// func db.Open(driverName string, settings db.DataSource)
+// --> (db.Database, error)
+sess, err := db.Open("mongo", settings)
 
 if err != nil {
-	panic(err)
+  panic(err)
 }
 
 defer sess.Close()
 ```
 
-### Querying the database
+### 4. Query collections
+
+You can refer to a specific table with `db.Database.Collection()`, use the
+returned `db.Collection` value to query the collection.
+
+```go
+// func db.Database.Collection(tableName string)
+// --> (db.Collection, error)
+people, _ := sess.Collection("people")
+
+// func db.Collection.FindAll(...interface{})
+// --> ([]db.Item, error)
+items, err := people.FindAll(
+  // Query condition
+  db.Cond { "name": "Peter" },
+)
+
+if err != nil {
+  panic(err.Error())
+}
+
+// Looping over the results.
+for _, item := range items {
+  fmt.Printf("Last name: %s\n", item["last_name"])
+}
+```
+
+### 5. What's next?
+
+Congratulations!
+
+Now that you know how to connecto to a database with `gosexy/db` you can use
+all the [db.Database](/gosexy/db/database) and
+[db.Collection](/gosexy/db/collection) methods.
 
-Check out the [gosexy/db documentation](/gosexy/db) for documentation in how to query
-a collection.
+For a few more code examples on MongoDB and `gosexy/db` see:
 
+* [Example](https://github.com/gosexy/db/blob/master/_examples/mongo/main.go)
+* [Test file](https://github.com/gosexy/db/blob/master/mongo/mongo_test.go)

markdown/db/wrappers/mysql.md

@@ -4,67 +4,97 @@ This package is a wrapper of
 [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql),
 a MySQL driver by [Julien Schmidt](http://www.julienschmidt.com/).
 
-## Installation
+## Usage example
 
-### Downloading and installing
+### 1. Get the wrapper
 
 ```sh
-go get menteslibres.net/gosexy/db/mysql
+go get -u menteslibres.net/gosexy/db
+go get -u menteslibres.net/gosexy/db/mysql
 ```
 
-#### Using go1.0.x?
+### 1. Import the wrapper
 
-There is an special extra step required to work with Julien's driver and
-**go1.0.x**.
+Import both the `gosexy/db` and the `gosexy/db/mysql` packages. The driver
+package must be imported to the
+[blank identifier](http://golang.org/doc/effective_go.html#blank) as we are not
+going to use any of its methods directly.
 
-If you're using **go1.1** the problem is already fixed.
-
-After you've pulled the package with `go get`, `cd` to the driver's path and
-checkout a special revision:
-
-```
-cd $GOPATH/src/github.com/go-sql-driver/mysql
-git checkout a8a04cc28d45f986dbb9c4c2e76e805bf7b17787
-go build && go install
+```go
+import (
+  "menteslibres.net/gosexy/db"
+  // Note the underscore at the beginning
+  _ "menteslibres.net/gosexy/db/mysql"
+)
 ```
 
-Then build `gosexy/db/mysql` again:
+### 3. Define how to connect to the database
 
-```
-cd $GOPATH/src/menteslibres.net/gosexy/db/mysql
-go build && go install
-```
+Use a `db.DataSource` variable to store the database settings.
 
-Please see this
-[issue](https://github.com/go-sql-driver/mysql/issues/48) to keep updated on
-this topic.
+```go
+var settings = db.DataSource{
+  Host:     "localhost",
+  Database: "test",
+  User:     "myuser",
+  Password: "mypass",
+}
+```
 
-## Usage
+### 3. Connect to the source.
 
-Import the `gosexy/db` and `gosexy/db/mysql` packages.
+Use `db.Open()` to request a connection to the database and
+`db.Database.Close()` to close it.
 
 ```go
-import (
-  "menteslibres.net/gosexy/db"
-	# Note that we are importing to the blank identifier.
-  _ "menteslibres.net/gosexy/db/mysql"
-)
+// func db.Open(driverName string, settings db.DataSource)
+// --> (db.Database, error)
+sess, err := db.Open("mysql", settings)
+
+if err != nil {
+  panic(err)
+}
+
+defer sess.Close()
 ```
 
-### Connecting to a MySQL database
+### 4. Query collections
+
+You can refer to a specific table with `db.Database.Collection()`, use the
+returned `db.Collection` value to query the collection.
 
 ```go
-sess, err := db.Open("mysql", db.DataSource{Host: "127.0.0.1", ...})
+// func db.Database.Collection(tableName string)
+// --> (db.Collection, error)
+people, _ := sess.Collection("people")
+
+// func db.Collection.FindAll(...interface{})
+// --> ([]db.Item, error)
+items, err := people.FindAll(
+  // Query condition
+  db.Cond { "name": "Peter" },
+)
 
 if err != nil {
-	panic(err)
+  panic(err.Error())
 }
 
-defer sess.Close()
+// Looping over the results.
+for _, item := range items {
+  fmt.Printf("Last name: %s\n", item["last_name"])
+}
 ```
 
-### Querying the database
+### 5. What's next?
+
+Congratulations!
+
+Now that you know how to connecto to a database with `gosexy/db` you can use
+all the [db.Database](/gosexy/db/database) and
+[db.Collection](/gosexy/db/collection) methods.
+
+For a few more code examples on MySQL and `gosexy/db` see:
 
-Check out the [gosexy/db documentation](/gosexy/db) for documentation in how to query
-a collection.
+* [Example](https://github.com/gosexy/db/blob/master/_examples/mysql/main.go)
+* [Test file](https://github.com/gosexy/db/blob/master/mysql/mysql_test.go)
 

markdown/db/wrappers/postgresql.md

@@ -101,6 +101,7 @@ For a few more code examples on PostgreSQL and `gosexy/db` see:
 
 In order to work with `gosexy/db` the original driver had to be
 [forked][1], the changes we made to it were incompatible with some of
-[pq][1]'s own features.
+[pq][2]'s own features.
 
 [1]: https://github.com/xiam/gopostgresql
+[2]: https://github.com/bmizerany/pq