From f9bb47b03d2c200528958a684194d5e009e7902c Mon Sep 17 00:00:00 2001
From: Lunny Xiao <xiaolunwen@gmail.com>
Date: Fri, 22 Nov 2013 13:05:10 +0800
Subject: [PATCH] improved docs

---
 README.md |  18 +++++-----
 doc.go    | 103 ++++++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 101 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index b3caea36..e362d9cb 100644
--- a/README.md
+++ b/README.md
@@ -12,11 +12,11 @@ Xorm is a simple and powerful ORM for Go.
  
 * Transaction Support
 
-* Both ORM and raw SQL Operation Support
+* Both ORM and raw SQL operation Support
 
 * Sync database sechmea Support
 
-* Query Cache speed up read
+* Query Cache speed up
 
 * Database Reverse support, See [Xorm Tool README](https://github.com/lunny/xorm/blob/master/xorm/README.md)
 
@@ -26,15 +26,13 @@ Xorm is a simple and powerful ORM for Go.
 
 Drivers for Go's sql package which currently support database/sql includes:
 
-* Mysql: [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
+* Mysql: [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
 
 * MyMysql: [github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv)
 
 * SQLite: [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
 
-* Postgres: [github.com/lib/pq](https://github.com/lib/pq)
-
-* Postgres: [github.com/bylevel/pq](https://github.com/bylevel/pq)
+* Postgres: [github.com/lib/pq](https://github.com/lib/pq)
 
 
 # Changelog
@@ -43,21 +41,21 @@ Drivers for Go's sql package which currently support database/sql includes:
 * **v0.2.1** : Added database reverse tool, now support generate go & c++ codes, see [Xorm Tool README](https://github.com/lunny/xorm/blob/master/xorm/README.md); some bug fixed.
 * **v0.2.0** : Added Cache supported, select is speeder up 3~5x; Added SameMapper for same name between struct and table; Added Sync method for auto added tables, columns, indexes;
 
-[More changelog ...](https://github.com/lunny/xorm/blob/master/Changelog.md)
+[More changelogs ...](https://github.com/lunny/xorm/blob/master/Changelog.md)
 
 
 # Installation
 
 	go get github.com/lunny/xorm
 
-# Documents 
-
-* [Quick Start](https://github.com/lunny/xorm/blob/master/docs/QuickStartEn.md)
+# Documents
 
 * [GoDoc](http://godoc.org/github.com/lunny/xorm)
 
 * [GoWalker](http://gowalker.org/github.com/lunny/xorm)
 
+* [Quick Start](https://github.com/lunny/xorm/blob/master/docs/QuickStartEn.md)
+
 # Cases
 
 * [Gowalker](http://gowalker.org) - [github.com/Unknwon/gowalker](http://github.com/Unknwon/gowalker)
diff --git a/doc.go b/doc.go
index 3c46bf2c..a0550ce0 100644
--- a/doc.go
+++ b/doc.go
@@ -5,41 +5,124 @@
 /*
 Package xorm is a simple and powerful ORM for Go.
 
-First, we should new an engine for a database
+Installation
+
+	go get github.com/lunny/xorm
+
+Create Engine
+
+Firstly, we should new an engine for a database
 
 	engine, err := xorm.NewEngine(driverName, dataSourceName)
 
 Method NewEngine's parameters is the same as sql.Open. It depends
-drivers' implementation. Generally, one engine is enough.
+drivers' implementation.
+Generally, one engine is enough. You can set it as package variable.
 
-There are 7 major methods and many helpful methods to use to operate database.
+Usage
+
+Xorm also support raw sql execution:
+
+1. query sql, the returned results is []map[string][]byte
+
+	results, err := engine.Query("select * from user")
+
+2. exec sql, the returned results
+
+	affected, err := engine.Exec("update user set .... where ...")
+
+There are 7 major ORM methods and many helpful methods to use to operate database.
 
 1. Insert one or multipe records to database
 
-	engine.Insert(...)
+	affected, err := engine.Insert(&struct)
+	// INSERT INTO struct () values ()
+	affected, err := engine.Insert(&struct1, &struct2)
+	// INSERT INTO struct1 () values ()
+	// INSERT INTO struct2 () values ()
+	affected, err := engine.Insert(&sliceOfStruct)
+	// INSERT INTO struct () values (),(),()
+	affected, err := engine.Insert(&struct1, &sliceOfStruct2)
+	// INSERT INTO struct1 () values ()
+	// INSERT INTO struct2 () values (),(),()
 
 2. Query one record from database
 
-	engine.Get(...)
+	has, err := engine.Get(&user)
+	// SELECT * FROM user LIMIT 1
 
 3. Query multiple records from database
 
-	engine.Find(...)
+	err := engine.Find(...)
+	// SELECT * FROM user
 
 4. Query multiple records and record by record handle
 
-	engine.Iterate(...)
+	err := engine.Iterate(...)
+	// SELECT * FROM user
 
 5. Update one or more records
 
-	engine.Update(...)
+	affected, err := engine.Update(&user)
+	// UPDATE user SET
 
 6. Delete one or more records
 
-	engine.Delete(...)
+	affected, err := engine.Delete(&user)
+	// DELETE FROM user Where ...
 
 7. Count records
 
-	engine.Count(...)
+	counts, err := engine.Count(&user)
+	// SELECT count(*) AS total FROM user
+
+Condition
+
+The above 7 methods could use with condition methods.
+
+1. Id, In
+
+	engine.Id(1).Get(&user)
+	// SELECT * FROM user WHERE id = 1
+
+2. Where, And, Or
+
+	engine.Where().And().Or().Find()
+	// SELECT * FROM user WHERE (.. AND ..) OR ...
+
+3. OrderBy, Asc, Desc
+
+	engine.Asc().Desc().Find()
+	// SELECT * FROM user ORDER BY .. ASC, .. DESC
+	engine.OrderBy().Find()
+	// SELECT * FROM user ORDER BY ..
+
+4. Limit, Top
+
+	engine.Limit().Find()
+	// SELECT * FROM user LIMIT .. OFFSET ..
+	engine.Top().Find()
+	// SELECT * FROM user LIMIT ..
+
+5. Sql
+
+	engine.Sql("select * from user").Find()
+
+6. Cols, Omit, Distinct
+
+	engine.Cols("col1, col2").Find()
+	// SELECT col1, col2 FROM user
+	engine.Omit("col1").Find()
+	// SELECT col2, col3 FROM user
+	engine.Distinct("col1").Find()
+	// SELECT DISTINCT col1 FROM user
+
+7. Join, GroupBy, Having
+
+	engine.GroupBy("name").Having("name='xlw'").Find()
+	//SELECT * FROM user GROUP BY name HAVING name='xlw'
+	engine.Join("LEFT", "userdetail", "user.id=userdetail.id").Find()
+	//SELECT * FROM user LEFT JOIN userdetail ON user.id=userdetail.id
+
 */
 package xorm