docs(readme) better example, test and tools doc

Makefile

@@ -1,6 +1,6 @@
 DEV_ROCKS=busted luacov luacov-coveralls luacheck ldoc
 
-.PHONY: instal dev clean test coverage lint doc
+.PHONY: install dev clean test coverage lint doc
 
 install:
 	@luarocks make lua-cassandra-*.rockspec

README.md

@@ -2,7 +2,16 @@
 
 A pure Lua client library for Apache Cassandra (2.0+), compatible with Lua and [ngx_lua].
 
-It is build on the model of the official Datastax drivers, and tries to implement the same behaviors and features.
+It is build following the example of the official Datastax drivers, and tries to implement the same behaviors, options and features.
+
+## Table of Contents
+
+- [Features](#features)
+- [Usage](#usage)
+- [Installation](#installation)
+- [Documentation and Examples](#documentation-and-examples)
+- [Test Suite](#test-suite)
+- [Tools](#tools)
 
 ## Features
 
@@ -13,7 +22,7 @@ It is build on the model of the official Datastax drivers, and tries to implemen
 - Configurable load balancing, reconnection and retry policies
 - TLS client-to-node encryption
 - Client authentication
-- Highly configurable options per session/request
+- Highly configurable options per session/query
 - Compatible with Cassandra 2.0 and 2.1
 - Works with Lua 5.1, 5.2, 5.3 and LuaJIT 2.x
 
@@ -32,7 +41,7 @@ http {
   server {
     ...
 
-    location /insert {
+    location / {
       content_by_lua '
         local cassandra = require "cassandra"
 
@@ -54,23 +63,6 @@ http {
           -- ...
         end
 
-        session:set_keep_alive()
-      ';
-    }
-
-    location /get {
-      content_by_lua '
-        local cassandra = require "cassandra"
-
-        local session, err = cassandra.spawn_session {
-          shm = "cassandra", -- defined by "lua_shared_dict"
-          contact_points = {"127.0.0.1"}
-        }
-        if err then
-          ngx.log(ngx.ERR, "Could not spawn session: ", tostring(err))
-          return ngx.exit(500)
-        end
-
         local rows, err = session:execute("SELECT * FROM users")
         if err then
           -- ...
@@ -106,7 +98,7 @@ assert(err == nil)
 local rows, err = session:execute("SELECT * FROM users")
 assert(err == nil)
 
-print("number of users: ", #rows)
+print("rows retrieved: ", #rows)
 
 session:shutdown()
 ```
@@ -119,26 +111,89 @@ With [Luarocks]:
 $ luarocks install lua-cassandra
 ```
 
-If installed manually, this module requires:
-
-- [lua-cjson](https://github.com/mpx/lua-cjson/)
-- [LuaSocket](http://w3.impa.br/~diego/software/luasocket/)
-- If you wish to use TLS client-to-node encryption, [LuaSec](https://github.com/brunoos/luasec)
+Manually:
 
-Once you have a local copy of this module's files under `src/`, add this to your Lua package path:
+Once you have a local copy of this module's `src/` fo   lder, add it to your `LUA_PATH` (or `lua_package_path` for ngx_lua):
 
 ```
 /path/to/src/?.lua;/path/to/src/?/init.lua;
 ```
 
+**Note**: If used *outside* of ngx_lua, this module requires:
+
+- [LuaSocket](http://w3.impa.br/~diego/software/luasocket/)
+- If you wish to use TLS client-to-node encryption, [LuaSec](https://github.com/brunoos/luasec)
+
 ## Documentation and examples
 
 The current [documentation] targets version `0.3.6` only. `0.4.0` documentation should come soon.
 
+## Test Suite
+
+This library uses three test suites:
+
+- Unit tests, with busted
+- Integration tests, with busted and a running Cassandra cluster
+- ngx_lua integration tests with Test::Nginx::Socket
+
+The first can simply be run after installing [busted](http://olivinelabs.com/busted/) and running:
+
+```shell
+$ busted spec/unit
+```
+
+The integration tests are located in another folder, and require a Cassandra instance to run on `localhost`:
+
+```shell
+$ busted spec/integration
+```
+
+Your cluster's hosts (not just the contact points, but all of them) should be declared in the `HOSTS` environment variable:
+
+```shell
+$ HOSTS=127.0.0.1,127.0.0.2,127.0.0.3 busted spec/integration
+```
+
+Finally, the ngx_lua integration tests can be run after installing the [Test::Nginx::Socket](http://search.cpan.org/~agent/Test-Nginx-0.23/lib/Test/Nginx/Socket.pm) module:
+
+```shell
+$ prove t/
+```
+
+## Tools
+
+This module can also use various tools for code quality, they can easily be installed from Luarocks by running:
+
+```
+$ make dev
+```
+
+Code coverage is analyzed by [luacov](http://keplerproject.github.io/luacov/) from the **busted** (unit and integration) tests:
+
+```shell
+$ busted --coverage
+$ luacov cassandra
+# or
+$ make coverage
+```
+
+The code is linted with [luacheck](https://github.com/mpeterv/luacheck). It is easier to use the Makefile again to avoid analyzing Lua files that are not part of this module:
+
+```shell
+$ make lint
+```
+
+The documentation is generated by [ldoc](https://github.com/stevedonovan/LDoc) and can be generated with:
+
+```shell
+$ ldoc -c doc/config.ld src
+# or
+$ make doc
+```
+
 [ngx_lua]: https://github.com/openresty/lua-nginx-module
 
 [Luarocks]: https://luarocks.org
-[lua-resty-cassandra]: https://github.com/jbochi/lua-resty-cassandra
 [documentation]: http://thibaultcha.github.io/lua-cassandra/
 [manual]: http://thibaultcha.github.io/lua-cassandra/manual/README.md.html
 

lua-cassandra-0.4.0-0.rockspec

@@ -5,7 +5,7 @@ source = {
   tag = "0.4.0"
 }
 description = {
-  summary = "Lua Cassandra client library",
+  summary = "Feature-rich client library for Cassandra",
   homepage = "http://thibaultcha.github.io/lua-cassandra",
   license = "MIT"
 }