Enhance a little bit the documentation

docs/source/apis.rst

@@ -6,7 +6,7 @@ APIs
 
 **GET** **/behavior**
 
-   Returns the current behavior in use.
+   Returns the current behavior in use, as a json object.
 
    Example::
 
@@ -18,14 +18,19 @@ APIs
 
 **POST** **/behavior**
 
-   Set the behavior. The behavior must be provided in a JSON mapping
+   Set the behavior. The behavior must be provided in a JSON object,
    in the body of the request, with a **name** key for the behavior
    name, and any option to pass to the behavior class.
 
+   .. note::
+
+        Don't forget to set the "application/json" Content-Type header
+        when doing your calls.
+
    Example::
 
       $ curl -d '{"sleep": 2, "name": "delay"}' http://localhost:8080/behavior \
-            -H "Content-Type: application/json"
+             -H "Content-Type: application/json"
        {
          "status": "ok"
        }

docs/source/examples.rst

@@ -8,24 +8,24 @@ Examples
 Proxying on an HTTP backend and sending back 50x errors 20% of the time::
 
     $ vaurien --protocol http --proxy 0.0.0.0:8888 --backend blog.ziade.org:80 \
-            --behavior 20:error
+              --behavior 20:error
 
 
 An SSL SMTP proxy with a 5% error rate and 10% delays::
 
     $ vaurien --proxy 0.0.0.0:6565 --backend mail.example.com:465 \
-            --protocol smtp --behavior 5:error,10:delay
+              --protocol smtp --behavior 5:error,10:delay
 
 An SSL SMTP Proxy that starts to error out after 12 calls (so in the middle of
 the transaction)::
 
     $ vaurien --proxy 0.0.0.0:6565 --backend mail.example.com:465 \
-            --protocol smtp --behavior 100:error --behavior-error-warmup 12
+              --protocol smtp --behavior 100:error --behavior-error-warmup 12
 
 
 Adding a 1 second delay on **every** call to a MySQL server::
 
     $ vaurien --proxy 0.0.0.0:3307 --backend 0.0.0.0:3306 --stay-connected --behavior 100:delay \
-        --handler-delay-sleep 1
+              --handler-delay-sleep 1
 
 

docs/source/extending.rst

@@ -33,14 +33,14 @@ signature::
 
         def __call__(self, client_sock, backend_sock, to_backend):
             # do something here
-            return True
+            return True  # or False, see after.
 
 
     Handler.register(MySuperHandler)
 
 
-Vaurien can use this handler and call it everytime data is being seen on one hand
-or the other.
+Vaurien can use this handler and call it when data comes from the backend (the
+server being proxied) or from a client (making calls to the server).
 
 You must call **Handler.register** against your class is order to add it
 to the list of the available plugins.

docs/source/index.rst

@@ -52,7 +52,7 @@ Design
 Vaurien is a TCP proxy that simply reads data sent to it and pass it to a
 backend, and vice-versa.
 
-It has built-in **protocols**: Tcp, Http, Redis & Memcache. The **Tcp** protocol
+It has built-in **protocols**: TCP, HTTP, Redis & Memcache. The **TCP** protocol
 is the default one and just sucks data on both sides and pass it along.
 
 Having higher-level protocols is mandatory in some cases, when Vaurien needs to
@@ -67,7 +67,7 @@ can be implemented in a behavior.
 Both **protocols** and **behaviors** are plugins, allowing you to extend Vaurien
 by adding new ones.
 
-Last, but not least, Vaurien provides a couple of APIs you can use to
+Last (but not least), Vaurien provides a couple of APIs you can use to
 change the behavior of the proxy live. That's handy when you are doing
 functional tests against your server: you can for instance start to add
 big delays and see how your web application reacts.
@@ -119,7 +119,7 @@ Controlling Vaurien live
 ========================
 
 
-Vaurien provides an HTTP server with a few APIs, which can be used to control
+Vaurien provides an HTTP server with an API, which can be used to control
 the proxy and change its behavior on the fly.
 
 To activate it, use the `--http` option::
@@ -179,15 +179,15 @@ Extending Vaurien
 Vaurien comes with a handful of useful :ref:`behaviors` and :ref:`protocols`,
 but you can create your own ones and plug them in a configuration file.
 
-In fact that's the best way to create realistic issues. Imagine that you
+In fact, that's the best way to create realistic issues: imagine you
 have a very specific type of error on your LDAP server everytime your
 infrastructure is under heavy load. You can reproduce this issue in your
 behavior and make sure your web application behaves as it should.
 
 Creating new behaviors and protocols is done by implementing classes with
 specific signatures.
 
-For example if you want to create a **super** behavior, you just have
+For example if you want to create a "*super*" behavior, you just have
 to write a class with two special methods: **on_before_handle** and
 **on_after_handle**.