Added better description of global parameters

Fixes #118

docs/api.rst

@@ -9,6 +9,21 @@ that the code makes distinction between positional and keyword arguments; we,
 however, recommend that people **use keyword arguments for all calls for
 consistency and safety**.
 
+.. note::
+
+    for compatibility with the Python ecosystem we use ``from_`` instead of
+    ``from`` and ``doc_type`` instead of ``type`` as parameter names.
+
+
+Global options
+--------------
+
+Some parameters are added by the client itself and can be used in all API
+calls.
+
+Ignore
+~~~~~~
+
 An API call is considered successful (and will return a response) if
 elasticsearch returns a 2XX response. Otherwise an instance of
 :class:`~elasticsearch.TransportError` (or a more specific subclass) will be
@@ -26,17 +41,25 @@ them::
     # ignore 404 and 400
     es.indices.delete(index='test-index', ignore=[400, 404])
 
-You can also specify ``request_timeout`` (float) as part of any API call, this
+
-value will get passed to the ``perform_request`` method of the connection
+Timeout
-class::
+~~~~~~~
+
+Global timeout can be set when constructing the client (see
+:class:`~elasticsearch.Connection`'s ``timeout`` parameter) or on a per-request
+basis using ``request_timeout`` (float value in seconds) as part of any API
+call, this value will get passed to the ``perform_request`` method of the
+connection class::
 
     # only wait for 1 second, regardless of the client's default
     es.cluster.health(wait_for_status='yellow', request_timeout=1)
 
 .. note::
 
-    for compatibility with the Python ecosystem we use ``from_`` instead of
+    Some API calls also accept a ``timeout`` parameter that is passed to
-    ``from`` and ``doc_type`` instead of ``type`` as parameter names.
+    Elasticsearch server. This timeout is internal and doesn't guarantee that the
+    request will end in the specified time.
+
 
 .. py:module:: elasticsearch