doc update

README.md

@@ -2,20 +2,53 @@
 
 Package `gocqlx` is a `gocql` extension, similar to what `sqlx` is to `database/sql`.
 
-It provides a new type that seamlessly wraps `gocql.Iter` and provide
+It contains wrappers over `gocql` types that provide convenience methods which
-convenience methods which are useful in the development of database driven
+are useful in the development of database driven applications.  Under the
-applications.  None of the underlying gocql.Iter methods are changed.
+hood it uses `sqlx/reflectx` package so `sqlx` models will also work with `gocqlx`.
-Instead all extended behavior is implemented through new methods defined on
-wrapper type.
-
-The wrapper type enables you to bind iterator row into a struct. Under the
-hood it uses `sqlx/reflectx` package, models / structs working whit `sqlx` will
-also work with `gocqlx`.
 
 ## Installation
 
     go get github.com/scylladb/gocqlx
 
+## Features
+
+Read all rows into a slice.
+
+```go
+var v []*Item
+if err := gocqlx.Select(&v, session.Query(`SELECT * FROM items WHERE id = ?`, id)); err != nil {
+    log.Fatal("select failed", err)
+}
+```
+
+Read a single row into a struct.
+
+```go
+var v Item
+if err := gocqlx.Get(&v, session.Query(`SELECT * FROM items WHERE id = ?`, id)); err != nil {
+    log.Fatal("get failed", err)
+}
+```
+
+Bind named query parameters from a struct or map.
+
+```go
+stmt, names, err := gocqlx.CompileNamedQuery([]byte("INSERT INTO items (id, name) VALUES (:id, :name)"))
+if err != nil {
+    t.Fatal("compile:", err)
+}
+q := gocqlx.Queryx{
+    Query: session.Query(stmt),
+    Names: names,
+}
+if err := q.BindStruct(&Item{"id", "name"}); err != nil {
+    t.Fatal("bind:", err)
+}
+if err := q.Query.Exec(); err != nil {
+    log.Fatal("get failed", err)
+}
+```
+
 ## Example
 
 See [example test](https://github.com/scylladb/gocqlx/blob/master/example_test.go).

doc.go

@@ -1,26 +1,38 @@
 // Package gocqlx is a gocql extension, similar to what sqlx is to database/sql.
 //
-// It provides a new type that seamlessly wraps gocql.Iter and provide
+// It contains wrappers over gocql types that provide convenience methods which
-// convenience methods which are useful in the development of database driven
+// are useful in the development of database driven applications.  Under the
-// applications.  None of the underlying gocql.Iter methods are changed.
+// hood it uses sqlx/reflectx package so sqlx models will also work with gocqlx.
-// Instead all extended behavior is implemented through new methods defined on
-// wrapper type.
 //
-// The wrapper type enables you to bind iterator row into a struct. Under the
+// Example, read all rows into a slice
-// hood it uses sqlx/reflectx package, models / structs working whit sqlx will
-// also work with gocqlx.
-//
-// Example, read all items for a given id
 //
 //     var v []*Item
 //     if err := gocqlx.Select(&v, session.Query(`SELECT * FROM items WHERE id = ?`, id)); err != nil {
 //         log.Fatal("select failed", err)
 //     }
 //
-// Example, read first item for a given id
+// Example, read a single row into a struct
 //
 //     var v Item
 //     if err := gocqlx.Get(&v, session.Query(`SELECT * FROM items WHERE id = ?`, id)); err != nil {
 //         log.Fatal("get failed", err)
 //     }
+//
+// Example, bind named query parameters from a struct or map
+//
+//     stmt, names, err := gocqlx.CompileNamedQuery([]byte("INSERT INTO items (id, name) VALUES (:id, :name)"))
+//     if err != nil {
+//         t.Fatal("compile:", err)
+//     }
+//     q := gocqlx.Queryx{
+//         Query: session.Query(stmt),
+//         Names: names,
+//     }
+//     if err := q.BindStruct(&Item{"id", "name"}); err != nil {
+//         t.Fatal("bind:", err)
+//     }
+//     if err := q.Query.Exec(); err != nil {
+//         log.Fatal("get failed", err)
+//     }
+//
 package gocqlx