Update documentation

[python-musicpdaio.git] / doc / source / explanations.rst

diff --git a/doc/source/explanations.rst b/doc/source/explanations.rst
index 48724bfeb60c46b24f5f5dd653252a2fa2f50877..15155a0df07dd35d6ac35a541ecaa3cace63394e 100644 (file)
--- a/doc/source/explanations.rst
+++ b/doc/source/explanations.rst
@@ -18,8 +18,8 @@ Should I use it?
 ----------------
 
  * If you need a plain MPD client to manage you MPD server, then stick with
-   no-ansynio module python-musicpd_
- * If you're building a interactive client, concurrent access to MPD or plugin
+   non-asyncio module python-musicpd_
+ * If you're building an interactive client, concurrent access to MPD or plugin
    into another asyncio project then use musicpdaio.
 
 
@@ -63,15 +63,32 @@ learn how to call commands and what kind of arguments they expect.
 
 Some examples are provided for the most common cases, see :ref:`tutorial`.
 
-For a list of currently supported commands in this python module see
-:ref:`commands`.
-
 **musicpdaio** tries to come with sane defaults, then running
-:py:class:`mpdaio.MPDClient` with no explicit argument will try defaults values
-to connect to MPD. Cf. :ref:`reference` for more about defaults.
+:py:class:`mpdaio.MPDClient` with no explicit argument will try default values
+to connect to MPD. Cf. :ref:`reference` for more about
+:ref:`defaults<default_settings>`.
+
+.. _socket_connections:
+.. index:: pair: connection pool; socket
+
+Socket connection
+-----------------
 
+**musicpdaio** uses a connection pool internally to keep already opened socket
+and reuse it.
+
+When first instantiated :py:class:`mpdaio.MPDClient` comes with an empty pool,
+when the first MPD command is called a connection is opened, saved and
+potentially reused later. In case a concurrent MPD command is called while the
+connection is still in use a new connection is made and kept in the pool.
+
+.. code-block:: python
 
-.. _environment_variables:
+   client = mpdaio.MPDClient()
+   client.connections    # Returns an empty list: []
+   client.version        # Returns empty string: ''
+   await client.ping()   # A connection is made and kept open
+   client.connections    # Returns a list; [Connection<example.org:6600>]
 
 
 .. _snake case: https://en.wikipedia.org/wiki/Snake_case