update package for godoc

README.md

@@ -2,7 +2,7 @@
 
 This is a **mock** driver as **database/sql/driver** which is very flexible and pragmatic to
 manage and mock expected queries. All the expectations should be met and all queries and actions
-triggered should be mocked in order to pass a test.
+triggered should be mocked in order to pass a test. See exported [api on godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock)
 
 ## Install
 
@@ -285,9 +285,12 @@ to compare them correctly, this may be improved.
 
     go test
 
+## Documentation
+
+See it on [godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock)
+
 ## TODO
 
-- export to godoc
 - handle argument comparison more efficiently
 
 ## Contributions

result.go

@@ -1,14 +1,14 @@
 package sqlmock
 
-// a structure which implements database/sql/driver.Result
+// Result satisfies sql driver Result, which
 // holds last insert id and rows affected
-// should be returned by Exec queries
+// by Exec queries
 type Result struct {
 	lastInsertId int64
 	rowsAffected int64
 }
 
-// creates a new result for Exec based query mocks
+// Creates a new Result for Exec based query mocks
 func NewResult(lastInsertId int64, rowsAffected int64) *Result {
 	return &Result{
 		lastInsertId,
@@ -16,12 +16,12 @@ func NewResult(lastInsertId int64, rowsAffected int64) *Result {
 	}
 }
 
-// get last insert id
+// Retrieve last inserted id
 func (res *Result) LastInsertId() (int64, error) {
 	return res.lastInsertId, nil
 }
 
-// get rows affected
+// Retrieve number rows affected
 func (res *Result) RowsAffected() (int64, error) {
 	return res.rowsAffected, nil
 }

rows.go

@@ -40,8 +40,8 @@ func (r *rows) Next(dest []driver.Value) error {
 	return nil
 }
 
-// create rows from a csv string
+// Create Rows from CSV string
-// to be used for mocked queries
+// to be used for mocked queries. Satisfies sql driver Rows interface
 func RowsFromCSVString(columns []string, s string) driver.Rows {
 	rs := &rows{}
 	rs.cols = columns

sqlmock.go

@@ -1,3 +1,56 @@
+/*
+Package sqlmock provides sql driver mock connecection, which allows to test database,
+create expectations and ensure the correct execution flow of any database operations.
+It hooks into Go standard library's database/sql package.
+
+The package provides convenient methods to mock database queries, transactions and
+expect the right execution flow, compare query arguments or even return error instead
+to simulate failures. See the example bellow, which illustrates how convenient it is
+to work with:
+
+
+    package main
+
+    import (
+        "database/sql"
+        "github.com/DATA-DOG/go-sqlmock"
+        "testing"
+        "fmt"
+    )
+
+    // will test that order with a different status, cannot be cancelled
+    func TestShouldNotCancelOrderWithNonPendingStatus(t *testing.T) {
+        // open database stub
+        db, err := sql.Open("mock", "")
+        if err != nil {
+            t.Errorf("An error '%s' was not expected when opening a stub database connection", err)
+        }
+
+        // columns to be used for result
+        columns := []string{"id", "status"}
+        // expect transaction begin
+        sqlmock.ExpectBegin()
+        // expect query to fetch order, match it with regexp
+        sqlmock.ExpectQuery("SELECT (.+) FROM orders (.+) FOR UPDATE").
+            WithArgs(1).
+            WillReturnRows(sqlmock.RowsFromCSVString(columns, "1,1"))
+        // expect transaction rollback, since order status is "cancelled"
+        sqlmock.ExpectRollback()
+
+        // run the cancel order function
+        someOrderId := 1
+        // call a function which executes expected database operations
+        err = cancelOrder(someOrderId, db)
+        if err != nil {
+            t.Errorf("Expected no error, but got %s instead", err)
+        }
+        // db.Close() ensures that all expectations have been met
+        if err = db.Close(); err != nil {
+            t.Errorf("Error '%s' was not expected while closing the database", err)
+        }
+    }
+
+*/
 package sqlmock
 
 import (
@@ -11,7 +64,7 @@ var mock *mockDriver
 
 // Mock interface defines a mock which is returned
 // by any expectation and can be detailed further
-// with the following methods
+// with the methods this interface provides
 type Mock interface {
 	WithArgs(...driver.Value) Mock
 	WillReturnError(error) Mock
@@ -23,7 +76,6 @@ type mockDriver struct {
 	conn *conn
 }
 
-// opens a mock driver database connection
 func (d *mockDriver) Open(dsn string) (driver.Conn, error) {
 	return mock.conn, nil
 }
@@ -33,7 +85,7 @@ func init() {
 	sql.Register("mock", mock)
 }
 
-// expect transaction to be started
+// Expect transaction to be started
 func ExpectBegin() Mock {
 	e := &expectedBegin{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -41,7 +93,7 @@ func ExpectBegin() Mock {
 	return mock.conn
 }
 
-// expect transaction to be commited
+// Expect transaction to be commited
 func ExpectCommit() Mock {
 	e := &expectedCommit{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -49,7 +101,7 @@ func ExpectCommit() Mock {
 	return mock.conn
 }
 
-// expect transaction to be rolled back
+// Expect transaction to be rolled back
 func ExpectRollback() Mock {
 	e := &expectedRollback{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -57,11 +109,14 @@ func ExpectRollback() Mock {
 	return mock.conn
 }
 
+// The expectation will return an error
 func (c *conn) WillReturnError(err error) Mock {
 	c.active.setError(err)
 	return c
 }
 
+// Expect database Exec to be triggered, which will match
+// the given query string as a regular expression
 func ExpectExec(sqlRegexStr string) Mock {
 	e := &expectedExec{}
 	e.sqlRegex = regexp.MustCompile(sqlRegexStr)
@@ -70,6 +125,8 @@ func ExpectExec(sqlRegexStr string) Mock {
 	return mock.conn
 }
 
+// Expect database Query to be triggered, which will match
+// the given query string as a regular expression
 func ExpectQuery(sqlRegexStr string) Mock {
 	e := &expectedQuery{}
 	e.sqlRegex = regexp.MustCompile(sqlRegexStr)
@@ -79,6 +136,8 @@ func ExpectQuery(sqlRegexStr string) Mock {
 	return mock.conn
 }
 
+// The expectation should be called with given arguments.
+// Works with Exec and Query expectations
 func (c *conn) WithArgs(args ...driver.Value) Mock {
 	eq, ok := c.active.(*expectedQuery)
 	if !ok {
@@ -93,6 +152,8 @@ func (c *conn) WithArgs(args ...driver.Value) Mock {
 	return c
 }
 
+// The expectation will return a Result.
+// Works only with Exec expectations
 func (c *conn) WillReturnResult(result driver.Result) Mock {
 	eq, ok := c.active.(*expectedExec)
 	if !ok {
@@ -102,6 +163,8 @@ func (c *conn) WillReturnResult(result driver.Result) Mock {
 	return c
 }
 
+// The expectation will return Rows.
+// Works only with Query expectations
 func (c *conn) WillReturnRows(rows driver.Rows) Mock {
 	eq, ok := c.active.(*expectedQuery)
 	if !ok {