added a whole bunch of documentation

Author: markbates

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Mark Bates
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -6,6 +6,17 @@ So what does Pop do exactly? Well, it wraps the absolutely amazing [https://gith
 
 Pop makes it easy to do CRUD operations, run migrations, and build/execute queries. Is Pop an ORM? I'll leave that up to you, the reader, to decide.
 
+Pop, by default, follows conventions that were defined by the ActiveRecord Ruby gem, http://www.rubyonrails.org. What does this mean?
+
+* Tables must have an "id" column and a corresponding "ID" field on the `struct` being used.
+* If there is a timestamp column named "created_at", "CreatedAt" on the `struct`, it will be set with the current time when the record is created.
+* If there is a timestamp column named "updated_at", "UpdatedAt" on the `struct`, it will be set with the current time when the record is updated.
+* Default databases are lowercase, underscored versions of the `struct` name. Examples: User{} is "users", FooBar{} is "foo_bars", etc...
+
+## Docs
+
+The API docs can be found at [http://godoc.org/github.com/markbates/pop](http://godoc.org/github.com/markbates/pop)
+
 ## Connecting to Databases
 
 Pop is easily configured using a YAML file. The configuration file should be stored in `config/database.yml` or `database.yml`.

belongs_to.go

@@ -12,7 +12,7 @@ func (c *Connection) BelongsTo(model interface{}) *Query {
 // "model" passed into it.
 func (q *Query) BelongsTo(model interface{}) *Query {
 	m := &Model{Value: model}
-	q.Where(fmt.Sprintf("%s = ?", m.AssociationName()), m.ID())
+	q.Where(fmt.Sprintf("%s = ?", m.associationName()), m.ID())
 	return q
 }
 

connection.go

@@ -8,8 +8,11 @@ import (
 	"github.com/markbates/going/defaults"
 )
 
+// Connections contains all of the available connections
 var Connections = map[string]*Connection{}
 
+// Connection represents all of the necessary details for
+// talking with a datastore
 type Connection struct {
 	Store   Store
 	Dialect Dialect
@@ -20,6 +23,8 @@ func (c *Connection) String() string {
 	return c.Dialect.URL()
 }
 
+// NewConnection creates a new connection, and sets it's `Dialect`
+// appropriately based on the `ConnectionDetails` passed into it.
 func NewConnection(deets *ConnectionDetails) *Connection {
 	c := &Connection{
 		Timings: []time.Duration{},
@@ -35,19 +40,30 @@ func NewConnection(deets *ConnectionDetails) *Connection {
 	return c
 }
 
+// Connect takes the name of a connection, default is "development", and will
+// return that connection from the available `Connections`. If a connection with
+// that name can not be found an error will be returned. If a connection is
+// found, and it has yet to open a connection with its underlying datastore,
+// a connection to that store will be opened.
 func Connect(e string) (*Connection, error) {
 	e = defaults.String(e, "development")
 	c := Connections[e]
 	if c == nil {
 		return c, fmt.Errorf("Could not find connection named %s!", e)
 	}
+	if c.Store != nil {
+		return c, nil
+	}
 	db, err := sqlx.Open(c.Dialect.Details().Dialect, c.Dialect.URL())
 	if err == nil {
 		c.Store = &dB{db}
 	}
 	return c, nil
 }
 
+// Transaction will start a new transaction on the connection. If the inner function
+// returns an error then the transaction will be rolled back, otherwise the transaction
+// will automatically commit at the end.
 func (c *Connection) Transaction(fn func(tx *Connection) error) error {
 	tx, err := c.Store.Transaction()
 	if err != nil {
@@ -67,6 +83,8 @@ func (c *Connection) Transaction(fn func(tx *Connection) error) error {
 	return err
 }
 
+// Rollback will open a new transaction and automatically rollback that transaction
+// when the inner function returns, regardless. This can be useful for tests, etc...
 func (c *Connection) Rollback(fn func(tx *Connection)) error {
 	tx, err := c.Store.Transaction()
 	if err != nil {
@@ -80,6 +98,8 @@ func (c *Connection) Rollback(fn func(tx *Connection)) error {
 	fn(cn)
 	return tx.Rollback()
 }
+
+// Q creates a new "empty" query for the current connection.
 func (c *Connection) Q() *Query {
 	return Q(c)
 }

dialect.go

@@ -32,7 +32,7 @@ func genericCreate(store Store, model *Model, cols Columns) error {
 	}
 	id, err = res.LastInsertId()
 	if err == nil {
-		model.SetID(int(id))
+		model.setID(int(id))
 	}
 	return err
 }

doc.go

@@ -0,0 +1,13 @@
+/*
+So what does Pop do exactly? Well, it wraps the absolutely amazing https://github.com/jmoiron/sqlx library. It cleans up some of the common patterns and workflows usually associated with dealing with databases in Go.
+
+Pop makes it easy to do CRUD operations, run migrations, and build/execute queries. Is Pop an ORM? I'll leave that up to you, the reader, to decide.
+
+Pop, by default, follows conventions that were defined by the ActiveRecord Ruby gem, http://www.rubyonrails.org. What does this mean?
+
+* Tables must have an "id" column and a corresponding "ID" field on the `struct` being used.
+* If there is a timestamp column named "created_at", "CreatedAt" on the `struct`, it will be set with the current time when the record is created.
+* If there is a timestamp column named "updated_at", "UpdatedAt" on the `struct`, it will be set with the current time when the record is updated.
+* Default databases are lowercase, underscored versions of the `struct` name. Examples: User{} is "users", FooBar{} is "foo_bars", etc...
+*/
+package pop

executors.go

@@ -31,8 +31,8 @@ func (c *Connection) Create(model interface{}, excludeColumns ...string) error {
 		cols := ColumnsForStruct(model, sm.TableName())
 		cols.Remove(excludeColumns...)
 
-		sm.TouchCreatedAt()
-		sm.TouchUpdatedAt()
+		sm.touchCreatedAt()
+		sm.touchUpdatedAt()
 
 		return c.Dialect.Create(c.Store, sm, cols)
 	})
@@ -46,7 +46,7 @@ func (c *Connection) Update(model interface{}, excludeColumns ...string) error {
 		cols.Remove("id", "created_at")
 		cols.Remove(excludeColumns...)
 
-		sm.TouchUpdatedAt()
+		sm.touchUpdatedAt()
 
 		return c.Dialect.Update(c.Store, sm, cols)
 	})

finders.go

@@ -2,18 +2,30 @@ package pop
 
 import "reflect"
 
+// Find the first record of the model in the database with a particular id.
+//
+//	c.Find(&User{}, 1)
 func (c *Connection) Find(model interface{}, id int) error {
 	return Q(c).Find(model, id)
 }
 
+// Find the first record of the model in the database with a particular id.
+//
+//	q.Find(&User{}, 1)
 func (q *Query) Find(model interface{}, id int) error {
 	return q.Where("id = ?", id).First(model)
 }
 
+// First record of the model in the database that matches the query.
+//
+//	c.First(&User{})
 func (c *Connection) First(model interface{}) error {
 	return Q(c).First(model)
 }
 
+// First record of the model in the database that matches the query.
+//
+//	q.Where("name = ?", "mark").First(&User{})
 func (q *Query) First(model interface{}) error {
 	return q.Connection.timeFunc("First", func() error {
 		q.Limit(1)
@@ -22,10 +34,16 @@ func (q *Query) First(model interface{}) error {
 	})
 }
 
+// Last record of the model in the database that matches the query.
+//
+//	c.Last(&User{})
 func (c *Connection) Last(model interface{}) error {
 	return Q(c).Last(model)
 }
 
+// Last record of the model in the database that matches the query.
+//
+//	q.Where("name = ?", "mark").Last(&User{})
 func (q *Query) Last(model interface{}) error {
 	return q.Connection.timeFunc("Last", func() error {
 		q.Limit(1)
@@ -35,10 +53,16 @@ func (q *Query) Last(model interface{}) error {
 	})
 }
 
+// All retrieves all of the records in the database that match the query.
+//
+//	c.All(&[]User{})
 func (c *Connection) All(models interface{}) error {
 	return Q(c).All(models)
 }
 
+// All retrieves all of the records in the database that match the query.
+//
+//	q.Where("name = ?", "mark").All(&[]User{})
 func (q *Query) All(models interface{}) error {
 	return q.Connection.timeFunc("All", func() error {
 		m := &Model{Value: models}
@@ -59,19 +83,25 @@ func (q *Query) All(models interface{}) error {
 	})
 }
 
-func (c *Connection) Exists(model interface{}) (bool, error) {
-	return Q(c).Exists(model)
-}
-
+// Exists returns true/false if a record exists in the database that matches
+// the query.
+//
+// 	q.Where("name = ?", "mark").Exists(&User{})
 func (q *Query) Exists(model interface{}) (bool, error) {
 	i, err := q.Count(model)
 	return i != 0, err
 }
 
+// Count the number of records in the database.
+//
+//	c.Count(&User{})
 func (c *Connection) Count(model interface{}) (int, error) {
 	return Q(c).Count(model)
 }
 
+// Count the number of records in the database.
+//
+//	q.Where("name = ?", "mark").Count(&User{})
 func (q Query) Count(model interface{}) (int, error) {
 	res := &rowCount{}
 	err := q.Connection.timeFunc("Count", func() error {