commit 16d7b9ffd9b77d051058798cff8633f7af143148
Author: Stavros Sachtouris <saxtouri@admin.grnet.gr>
Date:   Thu Sep 26 14:14:03 2013 +0300

    Update and correct kamaki.clients documentation

diff --git a/docs/commands.rst b/docs/commands.rst
index 8c0e1cd..7d616d3 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -143,16 +143,16 @@ server (Compute/Cyclades)
 
 .. code-block:: text
 
-    addr    :  List a server's nic address
+    addr    :  List a server nic address
     console :  Get a VNC console
     create  :  Create a server
     delete  :  Delete a server
-    firewall:  Manage server's firewall profile
-        set :  Set the server's firewall profile
-        get :  Get the server's firewall profile
+    firewall:  Manage server firewall profile
+        set :  Set the server firewall profile
+        get :  Get the server firewall profile
     ip      :  Manage floating IPs for the servers
         attach:  Attach a floating ip to a server with server_id
-        info  :  A floating IPs' details
+        info  :  A floating IP details
         detach:  Detach floating ip from server
         list  :  List all floating ips
         create:  Create a new floating IP
@@ -165,7 +165,7 @@ server (Compute/Cyclades)
         set   :  Add / update server metadata
         delete:  Delete a piece of server metadata
     reboot  :  Reboot a server
-    rename  :  Update a server's name
+    rename  :  Update a server name
     shutdown:  Shutdown a server
     start   :  Start a server
     stats   :  Get server statistics
@@ -445,12 +445,12 @@ Showcase: Upload and download a file
     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
     [file]: !diff rndm_local.file rndm_remote.file
 
-.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g. bash)
+.. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g., bash)
 
 .. warning:: The container:object/path syntax does not function if the
     container and / or the object path contain one or more : characters. To use
     containers and objects with : use the --container and --dst-container
-    arguments, e.g. to copy test.py object from example:dev container to
+    arguments, e.g., to copy test.py object from example:dev container to
     example:deploy ::
 
         $ kamaki file copy --container=example:dev test.py --dst-container=example:deploy
diff --git a/docs/developers/adding-commands.rst b/docs/developers/adding-commands.rst
index efe5265..9e4bac9 100644
--- a/docs/developers/adding-commands.rst
+++ b/docs/developers/adding-commands.rst
@@ -2,29 +2,31 @@ Adding Commands
 ===============
 
 Kamaki commands are implemented as python classes, decorated with a special
-decorator called *command*. This decorator is a method of kamaki.cli that adds
-a new command in a CommandTree structure (kamaki.cli.commant_tree). The later
-is used by interfaces to manage kamaki commands.
+decorator called *command*. This decorator is a method of *kamaki.cli* that
+adds a new command in a *CommandTree* structure. A *CommandTree* (package
+*kamaki.cli.commant_tree*) is a data structure used by kamaki to manage command
+namespaces.
 
-In the following, a set of kamaki commands will be implemented::
+For demonstration purposes, the following set of kamaki commands will be
+implemented in this document::
 
     mygrp1 list all                         //show a list
     mygrp1 list details [--match=<>]        //show list of details
     mygrp2 list all [regular expression] [-l]       //list all subjects
     mygrp2 info <id> [name]      //get information for subject with id
 
-There are two command sets to implement, namely mygrp1 and mygrp2. The first
-will contain two commands, namely list-all and list-details. The second one
-will also contain two commands, list-all and info. To avoid ambiguities,
-command names should rather be prefixed with the group they belong to, e.g.
-mygrp1-list-all and mygrp2-list-all.
+There are two command groups to implement i.e., *mygrp1* and *mygrp2*,
+containing two commands each (*list_all*, *list_details* and *list_all*, *info*
+respectively). To avoid ambiguities, command names are prefixed with the
+command group they belong to, e.g., *mygrp1_list_all* and *mygrp2_list_all*.
+The underscore is used to separate command namespaces.
 
-The first command has the simplest possible syntax: no parameters, no runtime
-arguments. The second accepts an optional runtime argument with a value. The
-third features an optional argument and an optional runtime flag argument. The
-last is an example of a command with an obligatory and an optional argument.
+The first command (*mygrp1_list_all*) has the simplest possible syntax: no
+parameters, no runtime arguments. The second accepts an optional runtime argument with a value. The third features an optional parameter and an optional
+runtime flag argument. The last is an example of a command with an obligatory
+and an optional parameter.
 
-Samples of the expected behavior in one-command mode are following:
+Examples of the expected behavior in one-command mode:
 
 .. code-block:: console
 
@@ -35,34 +37,32 @@ Samples of the expected behavior in one-command mode are following:
          - - - -
         list
     $ kamaki mygrp1 list
-        Syntax Error
 
         Options
          - - - -
         all        show a list
         details     show a list of details
     $ kamaki mygrp1 list all
-        ... (mygrp1 client method is called) ...
+        ... (a mygrp1_list_all instance runs) ...
     $ kamaki mygrp2 list all 'Z[.]' -l
-        ... (mygrp2 client method is called) ...
+        ... (a mygrp2_list_all instance runs) ...
     $
 
-The above example will be used throughout the present guide.
-
 The CommandTree structure
 -------------------------
 
-CommandTree manages a command by its path. Each command is stored in multiple
-nodes on the tree, so that the last term is a leaf and the route from root to
-that leaf represents the command path. For example the commands *file upload*,
-*file list* and *file info* are stored together as shown bellow::
+CommandTree manages a command by its namespace. Each command is stored in
+a tree path, where each node is a name. A leaf is the end term of a namespace and contains a pointer to the command class to be executed.
+
+Here is an example from the actual kamaki command structure, where the commands
+*file upload*, *file list* and *file info* are represented as shown bellow::
 
     - file
     ''''''''|- info
             |- list
             |- upload
 
-The example used in the present, should result to the creation of two trees::
+Now, let's load the showcase example on CommandTrees::
 
     - mygrp1
     ''''''''|- list
@@ -74,12 +74,12 @@ The example used in the present, should result to the creation of two trees::
             '''''''|- all
             |- info
 
-Each command group should be stored on a different CommandTree. For that
-reason, command specification modules should contain a list of CommandTree
-objects, named *_commands*
+Each command group should be stored on a different CommandTree.
+
+For that reason, command specification modules should contain a list of CommandTree objects, named *_commands*. This mechanism allows any interface
+application to load the list of commands from the *_commands* array.
 
-A command group information (name, description) is provided at CommandTree
-structure initialization:
+The first name of the command path and a description (name, description) are needed to initializeg a CommandTree:
 
 .. code-block:: python
 
@@ -88,15 +88,19 @@ structure initialization:
 
     _commands = [_mygrp1_commands, _mygrp2_commands]
 
+
 The command decorator
 ---------------------
 
-The *command* decorator mines all the information necessary to build a command
-specification which is then inserted in a CommanTree instance::
+All commands are specified by subclasses of *kamaki.cli.commands._command_init*
+These classes are called "command specifications".
+
+The *command* decorator mines all the information needed to build a namespace
+from a command specification::
 
     class code  --->  command()  -->  updated CommandTree structure
 
-Kamaki interfaces make use of this CommandTree structure. Optimizations are
+Kamaki interfaces make use of the CommandTree structure. Optimizations are
 possible by using special parameters on the command decorator method.
 
 .. code-block:: python
@@ -108,14 +112,16 @@ possible by using special parameters on the command decorator method.
 
         :param prefix: of the commands allowed to be inserted ('' for all)
 
-        :param descedants_depth: is the depth of the tree descedants of the
+        :param descedants_depth: is the depth of the tree descendants of the
             prefix command.
     """
 
 Creating a new command specification set
 ----------------------------------------
 
-A command specification developer should create a new module (python file) with as many classes as the command specifications to be offered. Each class should be decorated with *command*.
+A command specification developer should create a new module (python file) with
+one command specification class per command. Each class should be decorated
+with *command*.
 
 .. code-block:: python
 
@@ -129,10 +135,10 @@ A command specification developer should create a new module (python file) with
     ...
 
 A list of CommandTree structures must exist in the module scope, with the name
-_commands, as shown above. Different CommandTree objects correspond to
-different command groups.
+*_commands*. Different CommandTree objects correspond to different command
+groups.
 
-Get command description
+Set command description
 -----------------------
 
 The description of each command is the first line of the class commend. The
@@ -143,25 +149,50 @@ subject with id*" description.
 
     ...
     @command(_mygrp2_commands)
-    class mygrp2_info()
-        """get information for subject with id"""
+    class mygrp2_info():
+        """get information for subject with id
+        Anything from this point and bellow constitutes the long description
+        Please, mind the indentation, pep8 is not forgiving.
+        """
         ...
 
+Description placeholders
+------------------------
+
+There is possible to create an empty command, that can act as a description
+placeholder. For example, the *mygrp1_list* namespace does not correspond to an
+executable command, but it can have a helpful description. In that case, create
+a command specification class with a command and no code:
+
+.. code-block:: python
+
+    @command(_mygrp1_commands)
+    class mygrp1_list():
+        """List mygrp1 objects.
+        There are two versions: short and detailed
+        """
+
+.. warning:: A command specification class with no description is invalid and
+    will cause an error.
+
 Declare run-time argument
 -------------------------
 
-The argument mechanism allows the definition of run-time arguments. Some basic
-argument types are defined at the
+A special argument mechanism allows the definition of run-time arguments. This
+mechanism is based on argparse and is designed to simplify argument definitions
+when specifying commands.
+
+Some basic argument types are defined at the
 `argument module <code.html#module-kamaki.cli.argument>`_, but it is not
-uncommon to extent these classes in order to achieve specialized type checking
-and syntax control (e.g. at
-`pithos cli module <code.html#module-kamaki.cli.commands.pithos>`_).
+a bad idea to extent these classes in order to achieve specialized type
+checking and syntax control. Still, in most cases, the argument types of the
+argument package are enough for most cases.
 
-To declare a run-time argument on a specific command, the object class should
-initialize a dict called *arguments* , where Argument objects are stored. Each
-argument object is a possible run-time argument. Syntax checking happens at
-client level, while the type checking is implemented in the Argument code
-(thus, many different Argument types might be needed).`
+To declare a run-time argument on a specific command, the specification class
+should contain a dict called *arguments* , where Argument objects are stored.
+Each argument object is a run-time argument. Syntax checking happens at client
+level, while the type checking is implemented in the Argument code (e.g.,
+IntArgument checks if the value is an int).
 
 .. code-block:: python
 
@@ -190,15 +221,15 @@ or more usually and elegantly:
 
         arguments = dict(
             match=ValueArgument(
-            'Filter output to match string', ('-m', --match'))
+                'Filter output to match string', ('-m', --match'))
         )
 
 Accessing run-time arguments
 ----------------------------
 
-To access run-time arguments, users can use the _command_init interface, which
-implements __item__ accessors to handle run-time argument values. In specific,
-an instance of _command_init can use brackets to set or read <argument>.value .
+To access run-time arguments, users can use the *_command_init* interface,
+which implements *__item__* accessors to handle run-time argument values. In
+other words, one may get the value of an argument with *self[<argument>]*.
 
 .. code-block:: python
 
@@ -222,9 +253,8 @@ an instance of _command_init can use brackets to set or read <argument>.value .
 The main method and command parameters
 --------------------------------------
 
-The command behavior for each command / class is coded in *main*. The
-parameters of *main* method defines the command parameters part of the syntax.
-In specific::
+The command behavior for each command class is coded in *main*. The
+parameters of *main* method affect the syntax of the command. In specific::
 
     main(self, param)                   - obligatory parameter <param>
     main(self, param=None)              - optional parameter [param]
@@ -236,8 +266,8 @@ In specific::
     main(self, *args)                   - arbitary number of params [...]
     main(self, param1____param2, *args) - <param1:param2> [...]
 
-The information that can be mined by *command* for each individual command is
-presented in the following:
+Let's have a look at the command specification class again, and highlight the
+parts that affect the command syntax:
 
 .. code-block:: python
     :linenos:
@@ -245,23 +275,32 @@ presented in the following:
     from kamaki.cli.argument import FlagArgument
     ...
 
-    _commands = [_mygrp1_commands, _mygrp2=commands]
+    _commands = [_mygrp1_commands, _mygrp2_commands]
     ...
 
     @command(_mygrp2_commands)
     class mygrp2_list_all():
-        """List all subjects"""
+        """List all subjects
+        Refers to the subject accessible by current user
+        """
 
         arguments = dict(FlagArgument('detailed list', '-l'))
 
         def main(self, reg_exp=None):
             ...
 
-This will load the following information on the CommandTree:
+The above lines contain the following information:
+
+* Namespace and name (line 8): mygrp2 list all
+* Short (line 9) and long (line 10) description
+* Parameters (line 15): [reg exp]
+* Runtime arguments (line 13): [-l]
+* Runtime arguments help (line 13): detailed list
 
-* Syntax (from lines 8,12,19): mygrp list all [reg exp] [-l]
-* Description (form line 9): List all subjects
-* Arguments help (from line 13,14): -l: detailed list
+.. tip:: It is suggested to code the main functionality in a member method
+    called *_run*. This allows the separation between syntax and logic. For
+    example, an external library may need to call a command without caring
+    about its command line behavior.
 
 Letting kamaki know
 -------------------
@@ -270,11 +309,11 @@ Kamaki will load a command specification *only* if it is set as a configurable
 option. To demonstrate this, let the command specifications coded above be
 stored in a file named *grps.py*.
 
-The developer should move file *grps.py* to kamaki/cli/commands, the default
-place for command specifications, although running a command specification from
-a different path is also a kamaki feature.
+The developer should move the file *grps.py* to *kamaki/cli/commands*, the
+default place for command specifications
 
-The user has to use a configuration file where the following is added:
+These lines should be contained in the kamaki configuration file for a new
+command specification module to work:
 ::
 
     [global]
@@ -288,9 +327,10 @@ or equivalently:
     $ kamaki config set mygrp1_cli grps
     $ kamaki config set mygrp2_cli grps
 
-Command specification modules don't need to live in kamaki/cli/commands,
-although this is suggested for uniformity. If a command module exist in another
-path::
+.. note:: running a command specification from a different path is supported.
+    To achieve this, add a *<group>_cli = </path/to/module>* line in the
+    configure file under the *global* section.
+::
 
     [global]
     mygrp_cli = /another/path/grps.py
@@ -320,12 +360,22 @@ Summary: create a command set
 
 
     @command(_mygrp1_commands)
+    class mygrp1_list(_command_init):
+        """List mygrp1 objects.
+        There are two versions: short and detailed
+        """
+
+
+    @command(_mygrp1_commands)
     class mygrp1_list_all(_command_init):
         """show a list"""
 
-        def main(self):
+        def _run():
             ...
 
+        def main(self):
+            self._run()
+
 
     @command(_mygrp1_commands)
     class mygrp1_list_details(_command_init):
@@ -336,11 +386,16 @@ Summary: create a command set
                 'Filter output to match string', ('-m', --match'))
         )
 
-        def main(self):
-            ...
+        def _run(self):
             match_value = self['match']
             ...
 
+        def main(self):
+        self._run()
+
+
+    #The following will also create a mygrp2_list command with no description
+
 
     @command(_mygrp2_commands)
     class mygrp2_list_all(_command_init):
@@ -350,21 +405,23 @@ Summary: create a command set
             list=FlagArgument('detailed listing', '-l')
         )
 
-        def main(self, regular_expression=None):
-            ...
-            detail_flag = self['list']
+        def _run(self, regexp):
             ...
-            if detail_flag:
+            if self['list']:
                 ...
-            ...
-            if regular_expression:
+            else:
                 ...
-            ...
+
+        def main(self, regular_expression=None):
+            self._run(regular_expression)
 
 
     @command(_mygrp2_commands)
     class mygrp2_info(_command_init):
         """get information for subject with id"""
 
-        def main(self, id, name=''):
+        def _run(self, grp_id, grp_name):
             ...
+
+        def main(self, id, name=''):
+            self._run(id, name) 
diff --git a/docs/developers/clients-api.rst b/docs/developers/clients-api.rst
index 8ec0051..e7d35df 100644
--- a/docs/developers/clients-api.rst
+++ b/docs/developers/clients-api.rst
@@ -3,28 +3,31 @@ Creating applications with kamaki API
 
 Kamaki features a clients API for building third-party client applications that
 communicate with OpenStack and / or Synnefo cloud services. The package is
-called kamaki.clients and servers as a lib.
+called *kamaki.clients* and serves as a lib.
 
-A showcase of an application built on kamaki.clients is kamaki.cli, the command
-line interface of kamaki.
+A showcase of an application built on *kamaki.clients* is *kamaki.cli*, the
+command line interface of kamaki.
 
 Since Synnefo services are build as OpenStack extensions, an inheritance
 approach has been chosen for implementing clients for both. In specific,
-the *compute*, *storage* and *image* modules are clients of the OS compute, OS
-object-store, respectively. On the contrary, all the other modules are Synnefo
-extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api*
-extent *storage*) or novel Synnefo services (e.g., *astakos* for IM, *image*
-for *plankton*).
+the *compute*, *storage* and *image* modules are client implementations for the
+OpenStack compute and OpenStack object-store APIs, respectively. The rest of the
+modules implement the Synnefo extensions (i.e., *cyclades* and 
+*cyclades_rest_api* extents *compute*, *pithos* and *pithos_rest_api* extent
+*storage*) or novel Synnefo services (*image* for *plankton*).
 
 Setup a client instance
 -----------------------
 
-External applications may instantiate one or more kamaki clients.
+There is a client for every API, therefore an external applications should
+instantiate they kamaki clients they need. For example, to manage virtual
+servers and stored objects / files, an application would probably need to
+instantiate the CycladesClient and PithosClient respectively.
 
 .. code-block:: python
     :emphasize-lines: 1
 
-    Example 1.1: Instantiate Cyclades and Pithos client
+    Example 1.1: Instantiate Cyclades and Pithos clients
 
 
     from kamaki.clients.cyclades import CycladesClient
@@ -33,21 +36,21 @@ External applications may instantiate one or more kamaki clients.
     my_cyclades_client = CycladesClient(base_url, token)
     my_pithos_client = PithosClient(base_url, token, account, container)
 
-.. note:: *cyclades* and *pithos* clients inherit all methods of *compute*
-    and *storage* clients respectively. Separate compute or storage objects
-    should be used only when implementing applications for strict OS Compute or
-    OS Storage services.
+.. note:: *cyclades* and *pithos* clients inherit ComputeClient from *compute*
+    and StorageClient from *storage*, respectively. Separate ComputeClient or
+    StorageClient objects should be used only when implementing applications for
+    strict OpenStack Compute or Storage services.
 
 Using endpoints to get the base_url
 -----------------------------------
 
-In OpenStack, each service (e.g. `compute`, `object-store`, etc.) has a number
-of `endpoints`. These `endpoints` are actually URIs that are needed as prefixes
-for the API calls the kamaki client generates. In this context, we need just
-one of these these `endpoints`, the `publicURL`, which is also referred to as
-`base_url` in kamaki client libraries.
+In OpenStack, each service (e.g., `compute`, `object-store`, etc.) has a number
+of `endpoints`. These `endpoints` are actually URIs that are used by kamaki as
+prefixes to form the corresponding API calls. Client applications need just
+one of these these `endpoints`, namely the `publicURL`, which is also referred
+to as `base_url` in kamaki client libraries.
 
-In general, this is the suggested way of getting the base_url::
+Here are instructions for getting the base_url for a service::
 
     1. From the deployment UI get the AUTHENTICATION_URL and TOKEN
         (Example 1.2)
@@ -59,9 +62,9 @@ In general, this is the suggested way of getting the base_url::
         (Example 1.3)
 
 The AstakosClient is a client for the Synnefo/Astakos server. Synnefo/Astakos
-is an advanced identity server based on OpenStack identity specifications.
-Therefore, it can be used to get the `base_url` values needed for initializing
-kamaki clients. Kamaki simplifies this process with the astakos client library.
+is an identity server that implements the OpenStack identity API. Therefore, it
+can be used to get the `base_url` values needed for initializing kamaki clients.
+Kamaki simplifies this process with the astakos client library.
 
 Let's review the process with examples.
 
@@ -93,24 +96,26 @@ clients only need the one labeled as ``publicURL``.
     pithos_endpoints = my_astakos_client.get_service_endpoints('object-store')
     pithos_base_url = pithos_endpoints['publicURL']
 
-The ``get_service_endpoints`` method gets the service name as an argument. Here
-are the service names for the most popular kamaki clients::
+The ``get_service_endpoints`` method is called with the service name as an
+argument. Here are the service names for the kamaki clients::
 
-    storage, pithos     -->     object-store
-    compute, cyclades   -->     compute
-    image               -->     image
-    astakos             -->     identity
+    storage.StorageClient, pithos.PithosClient      -->     object-store
+    compute.ComputeClient, cyclades.CycladesClient  -->     compute
+    image.ImageClient                               -->     image
+    astakos.AstakosClient                           -->     identity, account
 
 Use client methods
 ------------------
 
-Client methods can now be called. Developers are advised to
-consult :ref:`the-client-api-ref` for details on the available methods and how
-to use them.
+At this point we assume that we can initialize a client, so the initialization
+step will be omitted in most of the examples that follow.
+
+The next step is to take a look at the member methods of each particular client.
+A detailed catalog of the member methods for all client classes can be found at
+:ref:`the-client-api-ref`
 
 In the following example, the *cyclades* and *pithos* clients of example 1.1
-are used to extract some information, that is then printed to the standard
-output.
+are used to extract some information through the remote service APIs. The information is then printed to the standard output.
 
 
 .. code-block:: python
@@ -119,7 +124,6 @@ output.
     Example 1.4: Print server name and OS for server with server_id
                 Print objects in container mycont
 
-
     srv = my_cyclades_client.get_server_info(server_id)
     print("Server Name: %s (with OS %s" % (srv['name'], srv['os']))
 
@@ -130,7 +134,7 @@ output.
 .. code-block:: console
     :emphasize-lines: 1
 
-    Run of examples 1.1 + 1.4
+    * A run of examples 1.1 + 1.4 *
 
 
     $ python test_script.py
@@ -143,14 +147,14 @@ output.
 Error handling
 --------------
 
-The kamaki.clients standard error is ClientError. A ClientError is raised for
-any kind of kamaki.clients errors (errors reported by servers, type errors in
+The *kamaki.clients* error class is ClientError. A ClientError is raised for
+any kind of *kamaki.clients* errors (errors reported by servers, type errors in
 arguments, etc.).
 
 A ClientError contains::
 
     message     The error message.
-    status      An optional error code, e.g. after a server error.
+    status      An optional error code, e.g., after a server error.
     details     Optional list of messages with error details.
 
 The following example concatenates examples 1.1 to 1.4 plus error handling
@@ -159,12 +163,15 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
 
     Example 1.5: Error handling
 
+    from kamaki.clients import ClientError
+
     from kamaki.clients.astakos import AstakosClient
     from kamaki.clients.cyclades import CycladesClient
     from kamaki.clients.pithos import PithosClient
 
     try:
         my_astakos_client = AstakosClient(AUTHENTICATION_URL, TOKEN)
+        my_astakos_client.authenticate()
     except ClientError:
         print('Failed to authenticate user token')
         return 1
@@ -297,3 +304,42 @@ Register a banch of pre-uploaded images
             print 'Image %s registered with id %s' % (r['name'], r['id'])
         except ClientError:
             print 'Failed to register image %s' % IMAGE_PATH
+
+Two servers and a private network
+'''''''''''''''''''''''''''''''''
+
+.. code-block:: python
+
+    #! /user/bin/python
+
+    from kamaki.clients.astakos import AstakosClient
+    from kamaki.clients.cyclades import CycladesClient
+
+    AUTHENTICATION_URL = 'https://accounts.example.com/identity/v2.0'
+    TOKEN = 'replace this with your token'
+
+    astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
+
+    cyclades_endpoints = user.get_service_endpoints('compute')
+    CYCLADES_URL = cyclades_endpoints['publicURL']
+
+    FLAVOR_ID = 'put your flavor id here'
+    IMAGE_ID = 'put your image id here'
+
+    cyclades = CycladesClient(CYCLADES_URL, TOKEN)
+
+    srv1 = cyclades.create_server('server 1', FLAVOR_ID, IMAGE_ID)
+    srv2 = cyclades.create_server('server 2', FLAVOR_ID, IMAGE_ID)
+
+    srv_state1 = cyclades.wait_server(srv1['id'])
+    assert srv_state1 in ('ACTIVE'), 'Server 1 built failure'
+
+    srv_state2 = cyclades.wait_server(srv2['id'])
+    assert srv_state2 in ('ACTIVE'), 'Server 2 built failure'
+
+    net = cyclades.create_network('My private network')
+    net_state = cyclades.wait_network(net['id'])
+    assert net_state in ('ACTIVE', ), 'Network built failure'
+
+    cyclades.connect_server(srv1['id'], net['id'])
+    cyclades.connect_server(srv2['id'], net['id'])
diff --git a/docs/developers/extending-clients-api.rst b/docs/developers/extending-clients-api.rst
index e206a95..110a7ac 100644
--- a/docs/developers/extending-clients-api.rst
+++ b/docs/developers/extending-clients-api.rst
@@ -1,8 +1,8 @@
 Extending kamaki.clients
 ========================
 
-By default, kamaki clients are REST clients (they manage HTTP requests and
-responses to communicate with services).
+By default, kamaki clients implement REST APIs, therefore they manage HTTP
+requests and responses to communicate with services.
 
 How to build a client
 ---------------------
@@ -17,6 +17,7 @@ to raise exceptions that can be handled by kamaki interfaces.
 
     from kamaki.clients import Client, ClientError
 
+
     class MyNewClient(Client):
         """MyNewClient Description Here"""
 
@@ -100,7 +101,7 @@ Going agile
 -----------
 
 The kamaki.clients package contains a set of fine-grained unit-tests for all
-its packages. 
+APIs. 
 
 .. note:: unit tests require the optional python-mock package, version 1.X or
     better
@@ -123,14 +124,14 @@ kamaki.clients
 
     $ python test.py
 
-To test a specific class, add the class name as an argument. E.g. for the
+To test a specific class, add the class name as an argument. e.g., for the
 Client class:
 
 .. code-block:: console
 
     $ python test.py Client
 
-To test a specific method in a class, apply an extra argument, e.g. for the
+To test a specific method in a class, apply an extra argument, e.g., for the
 request method in the Client class:
 
 .. code-block:: console
@@ -138,7 +139,7 @@ request method in the Client class:
     $ python test.py Client request
 
 Each package contains a test module (test.py) which is also runnable from the
-command line. E.g. in the pithos package there is a test module which
+command line. e.g., in the pithos package there is a test module which
 contains, among others, the **download** sub-test:
 
 .. code-block:: console
@@ -154,7 +155,7 @@ contains, among others, the **download** sub-test:
     # Test kamaki.clients.pithos.PithosClient.download
     $ python test.py Pithos download
 
-To fully test a specific package, run test.py from the package location. E.g.
+To fully test a specific package, run test.py from the package location. e.g.,
 to test everything in kamaki.clients.pithos package:
 
 .. code-block:: console
@@ -169,23 +170,22 @@ Each folder / package contains a test.py file, that represents the test module
 of this package. All test modules contain a set of classes that extent the
 TestCase class. They also contain a main method to run the tests.
 
-By convention, testing classes are named as <Tested Class> where <Test Class>
-is the name of the tested class or module. Methods not grouped in classes are
-tested by classes named after their respective module.
+By convention, testing classes have the same name as the class they test.
+Methods not grouped in classes are tested by classes named after their
+respective module.
 
-For example, the kamaki.clients.pithos.PithosClient class is tested by the
-kamaki.clients.pithos.test.PithosClient class, while the methods in
-kamaki.clients.utils module are tested by the kamaki.clients.utils.test.Utils
-testing class.
+For example, the *kamaki.clients.pithos.PithosClient* class is tested by the
+*kamaki.clients.pithos.test.PithosClient* class, while the methods in
+*kamaki.clients.utils* module are tested by *kamaki.clients.utils.test.Utils*.
 
 Adding unit tests
 ^^^^^^^^^^^^^^^^^
 
-After modifying or extending kamaki.clients method, classes, modules or
+After modifying or extending *kamaki.clients* method, classes, modules or
 packages, it is a good practice to also modify or extend the corresponding
 unit tests. What's more, it is recommended to modify or implement the testing
-of new behavior before implementing the behavior itself. The aim for
-kamaki.clients package is an 1 to 1 mapping between methods and their tests.
+of new behavior before implementing the behavior itself. The goal is to
+preserve an 1 to 1 mapping between methods and their tests.
 
 Modifying an existing method
 """"""""""""""""""""""""""""
@@ -195,24 +195,20 @@ corresponding test as well. By convention, the test method is located in the
 test module under the same package, in a TestCase subclass that is named with a
 name similar to the package or class that contains the tested method.
 
-Example 1: to modify the kamaki.clients.utils.filter_in method, the programmer
-has to also adjust the kamaki.clients.utils.test.Utils.test_filter_in method.
-
-Example 2: to modify the kamaki.clients.pithos.PithosRestClient.object_get, the
+Example: to modify *kamaki.clients.pithos.PithosRestClient.object_get*, the
 programmer has to also adjust the
-kamaki.clients.pithos.test.PithosRestClient.test_object_get method.
+*kamaki.clients.pithos.test.PithosRestClient.test.object_get* method.
 
 Adding a new method
 """""""""""""""""""
 
-Programmers who want to implement a new method in an existing class, are
-encouraged to implement the corresponding unit test first. In order to do that,
-they should find the testing class that is mapped to the class or module they
-need to extend.
+To implement a new method in an existing class, developers are encouraged to
+implement the corresponding unit test first. In order to do that, they should
+find the testing class that is mapped to the class or module they working on.
 
-Example 1: To add a **list_special** method to
-kamaki.clients.astakos.AstakosClient, extend the
-kamaki.clients.astakos.test.AstakosClient class, as shown bellow:
+Example: Adding **list_special** to *kamaki.clients.astakos.AstakosClient*,
+requires changes to *kamaki.clients.astakos.test.AstakosClient* too, as shown
+bellow:
 
 .. code-block:: python
 
@@ -224,42 +220,29 @@ kamaki.clients.astakos.test.AstakosClient class, as shown bellow:
             """Test the list_special method"""
             ...
 
-Example 2: To add a **get_random_int** method in kamaki.clients.utils module,
-extend the kamaki.clients.utils.test.Utils test class, as shown bellow:
-
-.. code-block:: python
-
-    # file: ${kamaki}/kamaki/clients/utils/__init__.py
-
-    class Utils(TestCase):
-        ...
-        def test_get_random_int(self):
-            """Test the get_random_int method"""
-            ...
-
 Implementing a new class or module
 """"""""""""""""""""""""""""""""""
 
 Each class or module needs a seperate test sub-module. By convention, each
-class or module under the kamaki.clients should be located in a separate
+class or module under *kamaki.clients*, should be located in a separate
 directory.
 
-Example 1: To add a NewService class that implements the kamaki.clients.Client
-interface: 
+Example 1: To add a NewService class that implements *kamaki.clients.Client*: 
 
-* create a new_service package and implement the unit tests in the kamaki.clients.new_service.test module:
+* create a new_service package and implement the unit tests in
+    *kamaki.clients.new_service.test*:
 
 .. code-block:: console
 
     $ mkdir new_service && touch new_service/test.py
 
-* create the file that will hold the package code and implement the module there:
+* create the file to code the package implementation:
 
 .. code-block:: console
 
     $ touch new_service/__init__.py
 
-* Create the test class and methods in kamaki.clients.new_service.test
+* Create the test class and methods in *kamaki.clients.new_service.test*
 
 .. code-block:: python
 
@@ -283,12 +266,11 @@ interface:
         def method1(self, ...):
             ...
 
-* Expose the new tests to top test module, by importing the test class to kamaki.clients.test
+* Import the test class to *kamaki.clients.test*:
 
-..code-block:: python
+.. code-block:: python
 
     # file: ${kamaki}/kamaki/clients/test.py
-
     from kamaki.clients.new_service.test import NewService
 
 .. note:: If the new class or module is part of an existing sub-package, it is
diff --git a/docs/developers/logging.rst b/docs/developers/logging.rst
index bbc7249..d9aded8 100644
--- a/docs/developers/logging.rst
+++ b/docs/developers/logging.rst
@@ -1,28 +1,27 @@
 Logging
 =======
 
-Kamaki uses the standard Python logger package to log some of its
-functionality.
+Kamaki uses the standard Python logger package to log some of its functionality.
 
-All kamaki loggers are named or prefixed after the package they log, e.g.
-a logger at `kamaki/cli/argument.__init__.py` should be called
+All kamaki loggers are named or prefixed after the package they log, e.g.,
+a logger at `kamaki/cli/argument/__init__.py` should be called
 `kamaki.cli.argument` whereas a logger at `kamaki/clients/conf.py` should be
-named `kamaki.clients/conf`. In `kamaki/clients/__init__.py` there are two
+named `kamaki.clients.conf`. In `kamaki/clients/__init__.py` there are two
 loggers that use the package name as prefix, and they detailed bellow.
 
 Monitor requests and responses
 ------------------------------
 
 The `kamaki.clients` logger contains two subloggers that monitor the HTTP
-communication of with the servers::
+API calls::
 
 	kamaki.clients.send   for kamaki requests to the server
 	kamaki.clients.recv   for server responses to kamaki
 
 These are the only loggers used for purposes other than mere debugging. Both
 loggers are defined in the CLI code and are used to (a) log HTTP communication
-to the log file as well as to (b) show users the HTTP requests and responses if
-kamaki cli is called with options like "verbose" or "debug".
+to the log file as well as to (b) show users the HTTP requests and responses in
+"verbose" or "debug" modes.
 
 Logger in external code
 -----------------------
@@ -68,12 +67,14 @@ that will contain logs of the form::
 	<   content-type: application/json; charset=UTF-8
 	< data size: 2425
 
-.. note:: user token and http body content are not logged by default
+.. note:: user token and http body content are not logged by default. This can
+	be switched on and off by modifing the *kamaki.client.Client.LOG_TOKEN* and
+	*kamaki.client.Client.LOG_DATA* flags
 
 As a second example, let's suppose that we need to see only the http requests
-of the `pithos.list_objects()` method. We decide to print these to the console.
-To achieve that goal, we should get a stream logger and deactivate it when we
-do not need it anymore.
+of the `pithos.list_objects()` method and print these to stdout. To achieve
+that goal, we should get a stream logger and deactivate it when we do not need
+it anymore.
 
 
 .. code-block:: python
diff --git a/docs/examplesdir/imageregister.rst b/docs/examplesdir/imageregister.rst
index b85c547..c4f1050 100644
--- a/docs/examplesdir/imageregister.rst
+++ b/docs/examplesdir/imageregister.rst
@@ -10,7 +10,7 @@ The image location format at user level::
 
     <container>:<object path>
 
-    e.g.:
+    e.g.,:
 
     pithos:debian_base3.diskdump
 
@@ -301,7 +301,7 @@ A look at the image metadata reveals that the name is changed:
 
 We can use the same idea to change the values of other metadata like disk
 format, container format or status. On the other hand, we cannot modify the
-id, owner, location, checksum and dates. E.g., to publish and unpublish:
+id, owner, location, checksum and dates. e.g., to publish and unpublish:
 
 .. code-block:: console
 
@@ -552,8 +552,8 @@ images:
 
     #!/bin/bash
 
-    userid=... # e.g. s0m3-u53r-1d
-    container=... # e.g. pithos
+    userid=... # e.g., s0m3-u53r-1d
+    container=... # e.g., pithos
 
     for path in images/*.diskdump; do
         location=$container:${path}
diff --git a/docs/examplesdir/server.rst b/docs/examplesdir/server.rst
index 76ec7f7..2d4dcc0 100644
--- a/docs/examplesdir/server.rst
+++ b/docs/examplesdir/server.rst
@@ -127,12 +127,12 @@ The syntax of the -p argument is something called "the personlity string"::
 
     -p <local file path>[,<remote path>[,<remote owner>[,<remote group>[,<mode>]]]]
 
-    e.g.
+    e.g.,
 
     -p /home/someuser/.ssh/id_rsa.pub,/root/.ssh/authorized_keys,root,root,0777
 
 .. note:: In case of omitting an optional part of the personality string, the
-    default behavior depends on the remote server, e.g. for a debian image we
+    default behavior depends on the remote server, e.g., for a debian image we
     expect the file to have root ownership, if the ownership is not specified.
 
 Create a virtual server while injecting current user public key to root account
@@ -194,5 +194,5 @@ You can now log to your remote virtual server as root, without a password. Well
 
 .. note:: There is no reason to limit injections to ssh keys. Users with an
     adequate understanding of the remote OS are encouraged to prepare and
-    inject all kinds of useful files, e.g. **lists of package sources**,
+    inject all kinds of useful files, e.g., **lists of package sources**,
     **default user profiles**, **device mount configurations**, etc.
diff --git a/docs/index.rst b/docs/index.rst
index d75d9e9..3e57d74 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,7 +12,7 @@ Kamaki project documentation
 development API for managing clouds.
 
 As a development library, it implements the OpenStack APIs,
-along with custom extensions as used by Synnefo
+along with the custom extensions introduced by Synnefo
 (`Synnefo IaaS <http://www.synnefo.org/>`_).
 
 ./kamaki is open source and released under a 2-clause BSD License.
diff --git a/docs/installation.rst b/docs/installation.rst
index 7ad1b9d..327add2 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -27,7 +27,7 @@ The following steps describe a command-line approach, but any graphic package ma
 
 .. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
 
-* Make sure the GPG public key for the Synnefo development team is added:
+* Make sure the GPG public key for the Synnefo repository is added:
 
     .. code-block:: console
 
@@ -86,7 +86,7 @@ Install mock (for developers only)
 
     $ sudo apt-get install python-mock
 
-.. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.::
+.. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.,::
 
     $ sudo apt-get install python-mock=1.0.1
 
@@ -118,8 +118,7 @@ Optional:
 Setup a virtual enviroment (optional)
 """""""""""""""""""""""""""""""""""""
 
-Use virtualenv to setup kamaki and Synnefo services in a sandbox
-environment.
+Use virtualenv to setup kamaki and Synnefo services in a sandbox environment.
 
 .. code-block:: console
 
diff --git a/docs/overview.rst b/docs/overview.rst
index e84af97..7c8213b 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -5,7 +5,7 @@ History
 -------
 
 Kamaki was created in 2011 by the `Synnefo <http://www.synnefo.org>`_
-development team of the *Greek Research and Technology Network (GRNET)*,
+development team at the *Greek Research and Technology Network (GRNET)*,
 initially as an internal project and later as a multipurpose tool for all
 users.
 
@@ -24,7 +24,7 @@ of Synnefo.
 Kamaki has been designed to act as a command line client as well as a python
 library for client developers. It is widely used in various Synnefo and okeanos
 components. Third parties are also encouraged to use the kamaki library for
-developing their own python-based cloud-client applications.
+developing their own python-based cloud applications.
 
 As Synnefo became a full, scalable and stable cloud solution, kamaki also
 evolved to an intuitive, multipurpose tool, available to a wider user base.
@@ -42,7 +42,7 @@ command-line tool for managing a local or remote Synnefo deployment.
 
 * internally by the Synnefo development team to test the Synnefo software,
 
-* by the deployment team which operates GRNET's ~okeanos service
+* by the deployment team which operates GRNET ~okeanos service
 
 * as the main Pithos+ client in Linux and other Unix-like environments
 
diff --git a/docs/setup.rst b/docs/setup.rst
index 2d10bc0..43e21a1 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -11,9 +11,9 @@ Quick Setup
 .. warning:: Users of kamaki 0.8.X or older should consult the
     `migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first.
 
-Kamaki has to be configured for a specific Synnefo deployment, with an
-authentication url and user token pair. Users should also pick an alias to name
-the cloud configuration. This can be any single word, e.g., "default",
+To set up Kamaki for a specific Synnefo deployment, users need an
+**authentication URL** and a **user token**. Users should also pick an alias to
+name the cloud configuration. This can be any single word, e.g., "default",
 "mycloud"or whatever suits the user.
 
 .. code-block:: console
@@ -21,7 +21,7 @@ the cloud configuration. This can be any single word, e.g., "default",
     $ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL>
     $ kamaki config set cloud.<cloud alias>.token myt0k3n==
 
-If only one cloud is configured, kamaki automatically picks it as the default.
+If only one cloud is configured, it is automatically considered the default.
 Otherwise, a default cloud should be specified:
 
 .. code-block:: console
@@ -80,7 +80,7 @@ the conversion mechanism for the configuration file.
 At this point, we should examine the kamaki output. Most options are renamed to
 match the latest configuration file version specifications.
 
-Let's take a look at the discarded options:
+Lets take a look at the discarded options:
 
 * `global.account` and `user.account` are not used anymore.
     The same is true for the synonyms `store.account` and `pithos.account`.
@@ -118,7 +118,7 @@ Multiple clouds
 ---------------
 
 The following refers to users of multiple Synnefo and/or Open Stack
-deployments. In the following, a Synnefo or Open Stack cloud deployment will
+deployments. In the following, a Synnefo (or Open Stack) cloud deployment will
 be called **a cloud**.
 
 Multiple clouds can be configured and manager in a single  kamaki setup, since
diff --git a/docs/usage.rst b/docs/usage.rst
index 18caf4b..d4312e7 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -40,8 +40,8 @@ messages. Still, there are some differences.
 
 In favor of interactive shell:
 
-* tab completion for commands (if supported by the user's shell)
-* session history with ↑ or ↓ keys (if supported by the user's shell)
+* tab completion for commands (if supported by the user shell)
+* session history with ↑ or ↓ keys (if supported by the user shell)
 * shorter commands with command context switching
 * re-run old commands with /history
 
@@ -248,7 +248,7 @@ command group (server) and of a command in that group (list).
                             filter by flavor id
 
     Details:
-    Use filtering arguments (e.g. --name-like) to manage long server lists
+    Use filtering arguments (e.g., --name-like) to manage long server lists
 
 .. _using-history-ref:
 
diff --git a/kamaki/cli/__init__.py b/kamaki/cli/__init__.py
index 0b91677..106cd0b 100644
--- a/kamaki/cli/__init__.py
+++ b/kamaki/cli/__init__.py
@@ -110,7 +110,7 @@ def _update_best_match(name_terms, prefix=[]):
 
 def command(cmd_tree, prefix='', descedants_depth=1):
     """Load a class as a command
-        e.g. spec_cmd0_cmd1 will be command spec cmd0
+        e.g., spec_cmd0_cmd1 will be command spec cmd0
 
         :param cmd_tree: is initialized in cmd_spec file and is the structure
             where commands are loaded. Var name should be _commands
diff --git a/kamaki/cli/command_tree/__init__.py b/kamaki/cli/command_tree/__init__.py
index 394712a..7302c1a 100644
--- a/kamaki/cli/command_tree/__init__.py
+++ b/kamaki/cli/command_tree/__init__.py
@@ -150,7 +150,7 @@ class CommandTree(object):
     def find_best_match(self, terms):
         """Find a command that best matches a given list of terms
 
-        :param terms: (list of str) match against paths in cmd_tree, e.g.
+        :param terms: (list of str) match against paths in cmd_tree, e.g.,
             ['aa', 'bb', 'cc'] matches aa_bb_cc
 
         :returns: (Command, list) the matching command, the remaining terms or
diff --git a/kamaki/cli/commands/astakos.py b/kamaki/cli/commands/astakos.py
index 6df73bf..8950aac 100644
--- a/kamaki/cli/commands/astakos.py
+++ b/kamaki/cli/commands/astakos.py
@@ -78,7 +78,7 @@ class _user_init(_command_init):
 @command(user_cmds)
 class user_authenticate(_user_init, _optional_json):
     """Authenticate a user
-    Get user information (e.g. unique account name) from token
+    Get user information (e.g., unique account name) from token
     Token should be set in settings:
     *  check if a token is set    /config whoami cloud.default.token
     *  permanently set a token    /config set cloud.default.token <token>
diff --git a/kamaki/cli/commands/cyclades.py b/kamaki/cli/commands/cyclades.py
index 5ba2382..1d8d30c 100644
--- a/kamaki/cli/commands/cyclades.py
+++ b/kamaki/cli/commands/cyclades.py
@@ -65,7 +65,7 @@ howto_personality = [
     '  SERVER_PATH: destination location inside server Image',
     '  OWNER: virtual servers user id of the remote destination file',
     '  GROUP: virtual servers group id or name of the destination file',
-    '  MODEL: permition in octal (e.g. 0777 or o+rwx)']
+    '  MODEL: permition in octal (e.g., 0777 or o+rwx)']
 
 
 class _service_wait(object):
@@ -136,7 +136,7 @@ class _init_cyclades(_command_init):
 @command(server_cmds)
 class server_list(_init_cyclades, _optional_json, _name_filter, _id_filter):
     """List virtual servers accessible by user
-    Use filtering arguments (e.g. --name-like) to manage long server lists
+    Use filtering arguments (e.g., --name-like) to manage long server lists
     """
 
     PERMANENTS = ('id', 'name')
@@ -259,7 +259,7 @@ class server_info(_init_cyclades, _optional_json):
     Contains:
     - name, id, status, create/update dates
     - network interfaces
-    - metadata (e.g. os, superuser) and diagnostics
+    - metadata (e.g., os, superuser) and diagnostics
     - hardware flavor and os image ids
     """
 
diff --git a/kamaki/cli/commands/history.py b/kamaki/cli/commands/history.py
index 24a62cb..480ffe1 100644
--- a/kamaki/cli/commands/history.py
+++ b/kamaki/cli/commands/history.py
@@ -91,8 +91,8 @@ class history_show(_init_history):
     .   2.  <order-id-1>-<order-id-2> : pick all commands ordered in the range
     .       [<order-id-1> - <order-id-2>]
     .   - the above can be mixed and repeated freely, separated by spaces
-    .       e.g. pick 2 4-7 -3
-    .   - Use negative integers to count from the end of the list, e.g.:
+    .       e.g., pick 2 4-7 -3
+    .   - Use negative integers to count from the end of the list, e.g.,:
     .       -2 means : the command before the last one
     .       -2-5 means : last 2 commands + the first 5
     .       -5--2 means : the last 5 commands except the last 2
@@ -151,7 +151,7 @@ class history_run(_init_history):
     .   1.  <order-id> : pick the <order-id>th command
     .   2.  <order-id-1>-<order-id-2> : pick all commands ordered in the range
     .       [<order-id-1> - <order-id-2>]
-    .   - Use negative integers to count from the end of the list, e.g.:
+    .   - Use negative integers to count from the end of the list, e.g.,:
     .       -2 means : the command before the last one
     .       -2-5 means : last 2 commands + the first 5
     .       -5--2 mean
diff --git a/kamaki/cli/commands/image.py b/kamaki/cli/commands/image.py
index 9ce89b3..d82a052 100644
--- a/kamaki/cli/commands/image.py
+++ b/kamaki/cli/commands/image.py
@@ -407,8 +407,8 @@ class image_meta_delete(_init_image, _optional_output_cmd):
 class image_register(_init_image, _optional_json):
     """(Re)Register an image file to an Image service
     The image file must be stored at a pithos repository
-    Some metadata can be set by user (e.g. disk-format) while others are set
-    only automatically (e.g. image id). There are also some custom user
+    Some metadata can be set by user (e.g., disk-format) while others are set
+    only automatically (e.g., image id). There are also some custom user
     metadata, called properties.
     A register command creates a remote meta file at
     .  <container>:<image path>.meta
diff --git a/kamaki/cli/commands/pithos.py b/kamaki/cli/commands/pithos.py
index 18fd11f..93df098 100644
--- a/kamaki/cli/commands/pithos.py
+++ b/kamaki/cli/commands/pithos.py
@@ -1884,7 +1884,7 @@ class file_containerlimit_set(_file_account_command, _optional_output_cmd):
                 msg = 'Failed to convert %s to bytes' % user_input,
                 raiseCLIError(qe, msg, details=[
                     'Syntax: containerlimit set <limit>[format] [container]',
-                    'e.g.: containerlimit set 2.3GB mycontainer',
+                    'e.g.,: containerlimit set 2.3GB mycontainer',
                     'Valid formats:',
                     '(*1024): B, KiB, MiB, GiB, TiB',
                     '(*1000): B, KB, MB, GB, TB'])
@@ -2036,7 +2036,7 @@ class file_versions(_file_container_command, _optional_json):
     Deleted objects may still have versions that can be used to restore it and
     get information about its previous state.
     The version number can be used in a number of other commands, like info,
-    copy, move, meta. See these commands for more information, e.g.
+    copy, move, meta. See these commands for more information, e.g.,
     /file info -h
     """
 
diff --git a/kamaki/cli/commands/snf-astakos.py b/kamaki/cli/commands/snf-astakos.py
index 032b301..e65b9ee 100644
--- a/kamaki/cli/commands/snf-astakos.py
+++ b/kamaki/cli/commands/snf-astakos.py
@@ -99,7 +99,7 @@ class _astakos_init(_command_init):
 @command(snfastakos_cmds)
 class astakos_user_info(_astakos_init, _optional_json):
     """Authenticate a user
-    Get user information (e.g. unique account name) from token
+    Get user information (e.g., unique account name) from token
     Token should be set in settings:
     *  check if a token is set    /config get cloud.default.token
     *  permanently set a token    /config set cloud.default.token <token>
@@ -412,10 +412,10 @@ class astakos_commission_resolve(_astakos_init, _optional_json):
 
     arguments = dict(
         accept=CommaSeparatedListArgument(
-            'commission ids to accept (e.g. --accept=11,12,13,...',
+            'commission ids to accept (e.g., --accept=11,12,13,...',
             '--accept'),
         reject=CommaSeparatedListArgument(
-            'commission ids to reject (e.g. --reject=11,12,13,...',
+            'commission ids to reject (e.g., --reject=11,12,13,...',
             '--reject'),
     )
 
