Updates to client docstrings

* Add a more precise description of cert_file
* change docstring placeholder to be compliant with sphinx rst

6 files changed, 412 insertions, 409 deletions

diff --git a/client/src/leap/soledad/client/__init__.py b/client/src/leap/soledad/client/__init__.py
index 4c6a41fc..1f54ef8c 100644
--- a/client/src/leap/soledad/client/__init__.py
+++ b/client/src/leap/soledad/client/__init__.py
@@ -226,25 +226,26 @@ class Soledad(object):
         """
         Initialize configuration, cryptographic keys and dbs.
 
-        @param uuid: User's uuid.
-        @type uuid: str
-        @param passphrase: The passphrase for locking and unlocking encryption
-            secrets for local and remote storage.
-        @type passphrase: str
-        @param secrets_path: Path for storing encrypted key used for
-            symmetric encryption.
-        @type secrets_path: str
-        @param local_db_path: Path for local encrypted storage db.
-        @type local_db_path: str
-        @param server_url: URL for Soledad server. This is used either to sync
+        :param uuid: User's uuid.
+        :type uuid: str
+        :param passphrase: The passphrase for locking and unlocking encryption
+                           secrets for local and remote storage.
+        :type passphrase: str
+        :param secrets_path: Path for storing encrypted key used for
+                             symmetric encryption.
+        :type secrets_path: str
+        :param local_db_path: Path for local encrypted storage db.
+        :type local_db_path: str
+        :param server_url: URL for Soledad server. This is used either to sync
             with the user's remote db and to interact with the shared recovery
             database.
-        @type server_url: str
-        @param cert_file: Path to the SSL certificate to use in the
-            connection to the server_url.
-        @type cert_file: str
-        @param auth_token: Authorization token for accessing remote databases.
-        @type auth_token: str
+        :type server_url: str
+        :param cert_file: Path to the certificate of the ca used
+                          to validate the SSL certificate used by the remote
+                          soledad server.
+        :type cert_file: str
+        :param auth_token: Authorization token for accessing remote databases.
+        :type auth_token: str
         """
         # get config params
         self._uuid = uuid
@@ -339,7 +340,7 @@ class Soledad(object):
         """
         Create work directories.
 
-        @raise OSError: in case file exists and is not a dir.
+        :raise OSError: in case file exists and is not a dir.
         """
         paths = map(
             lambda x: os.path.dirname(x),
@@ -418,8 +419,8 @@ class Soledad(object):
         Storage secret is encrypted before being stored. This method decrypts
         and returns the stored secret.
 
-        @return: The storage secret.
-        @rtype: str
+        :return: The storage secret.
+        :rtype: str
         """
         # calculate the encryption key
         key = scrypt.hash(
@@ -478,8 +479,8 @@ class Soledad(object):
         """
         Return whether there is a storage secret available for use or not.
 
-        @return: Whether there's a storage secret for symmetric encryption.
-        @rtype: bool
+        :return: Whether there's a storage secret for symmetric encryption.
+        :rtype: bool
         """
         if self._secret_id is None or self._secret_id not in self._secrets:
             try:
@@ -515,8 +516,8 @@ class Soledad(object):
                 }
             }
 
-        @return: The id of the generated secret.
-        @rtype: str
+        :return: The id of the generated secret.
+        :rtype: str
         """
         signal(SOLEDAD_CREATING_KEYS, self._uuid)
         # generate random secret
@@ -571,10 +572,10 @@ class Soledad(object):
         """
         Change the passphrase that encrypts the storage secret.
 
-        @param new_passphrase: The new passphrase.
-        @type new_passphrase: str
+        :param new_passphrase: The new passphrase.
+        :type new_passphrase: str
 
-        @raise NoStorageSecret: Raised if there's no storage secret available.
+        :raise NoStorageSecret: Raised if there's no storage secret available.
         """
         # maybe we want to add more checks to guarantee passphrase is
         # reasonable?
@@ -616,8 +617,8 @@ class Soledad(object):
         Calculate a hash for storing/retrieving key material on shared
         database, based on user's uuid.
 
-        @return: the hash
-        @rtype: str
+        :return: the hash
+        :rtype: str
         """
         return sha256(
             '%s%s' % (
@@ -639,8 +640,8 @@ class Soledad(object):
         Retrieve the document with encrypted key material from the shared
         database.
 
-        @return: a document with encrypted key material in its contents
-        @rtype: SoledadDocument
+        :return: a document with encrypted key material in its contents
+        :rtype: SoledadDocument
         """
         signal(SOLEDAD_DOWNLOADING_KEYS, self._uuid)
         db = self._shared_db()
@@ -687,11 +688,11 @@ class Soledad(object):
         """
         Update a document in the local encrypted database.
 
-        @param doc: the document to update
-        @type doc: SoledadDocument
+        :param doc: the document to update
+        :type doc: SoledadDocument
 
-        @return: the new revision identifier for the document
-        @rtype: str
+        :return: the new revision identifier for the document
+        :rtype: str
         """
         return self._db.put_doc(doc)
 
@@ -699,11 +700,11 @@ class Soledad(object):
         """
         Delete a document from the local encrypted database.
 
-        @param doc: the document to delete
-        @type doc: SoledadDocument
+        :param doc: the document to delete
+        :type doc: SoledadDocument
 
-        @return: the new revision identifier for the document
-        @rtype: str
+        :return: the new revision identifier for the document
+        :rtype: str
         """
         return self._db.delete_doc(doc)
 
@@ -711,15 +712,15 @@ class Soledad(object):
         """
         Retrieve a document from the local encrypted database.
 
-        @param doc_id: the unique document identifier
-        @type doc_id: str
-        @param include_deleted: if True, deleted documents will be
-            returned with empty content; otherwise asking for a deleted
-            document will return None
-        @type include_deleted: bool
+        :param doc_id: the unique document identifier
+        :type doc_id: str
+        :param include_deleted: if True, deleted documents will be
+                                returned with empty content; otherwise asking
+                                for a deleted document will return None
+        :type include_deleted: bool
 
-        @return: the document object or None
-        @rtype: SoledadDocument
+        :return: the document object or None
+        :rtype: SoledadDocument
         """
         return self._db.get_doc(doc_id, include_deleted=include_deleted)
 
@@ -728,15 +729,15 @@ class Soledad(object):
         """
         Get the content for many documents.
 
-        @param doc_ids: a list of document identifiers
-        @type doc_ids: list
-        @param check_for_conflicts: if set False, then the conflict check will
+        :param doc_ids: a list of document identifiers
+        :type doc_ids: list
+        :param check_for_conflicts: if set False, then the conflict check will
             be skipped, and 'None' will be returned instead of True/False
-        @type check_for_conflicts: bool
+        :type check_for_conflicts: bool
 
-        @return: iterable giving the Document object for each document id
+        :return: iterable giving the Document object for each document id
             in matching doc_ids order.
-        @rtype: generator
+        :rtype: generator
         """
         return self._db.get_docs(doc_ids,
                                  check_for_conflicts=check_for_conflicts,
@@ -745,12 +746,12 @@ class Soledad(object):
     def get_all_docs(self, include_deleted=False):
         """Get the JSON content for all documents in the database.
 
-        @param include_deleted: If set to True, deleted documents will be
-            returned with empty content. Otherwise deleted documents will not
-            be included in the results.
-        @return: (generation, [Document])
-            The current generation of the database, followed by a list of all
-            the documents in the database.
+        :param include_deleted: If set to True, deleted documents will be
+                                returned with empty content. Otherwise deleted
+                                documents will not be included in the results.
+        :return: (generation, [Document])
+                 The current generation of the database, followed by a list of
+                 all the documents in the database.
         """
         return self._db.get_all_docs(include_deleted)
 
@@ -758,13 +759,13 @@ class Soledad(object):
         """
         Create a new document in the local encrypted database.
 
-        @param content: the contents of the new document
-        @type content: dict
-        @param doc_id: an optional identifier specifying the document id
-        @type doc_id: str
+        :param content: the contents of the new document
+        :type content: dict
+        :param doc_id: an optional identifier specifying the document id
+        :type doc_id: str
 
-        @return: the new document
-        @rtype: SoledadDocument
+        :return: the new document
+        :rtype: SoledadDocument
         """
         return self._db.create_doc(content, doc_id=doc_id)
 
@@ -778,12 +779,12 @@ class Soledad(object):
         If the database specifies a maximum document size and the document
         exceeds it, create will fail and raise a DocumentTooBig exception.
 
-        @param json: The JSON document string
-        @type json: str
-        @param doc_id: An optional identifier specifying the document id.
-        @type doc_id:
-        @return: The new cocument
-        @rtype: SoledadDocument
+        :param json: The JSON document string
+        :type json: str
+        :param doc_id: An optional identifier specifying the document id.
+        :type doc_id:
+        :return: The new cocument
+        :rtype: SoledadDocument
         """
         return self._db.create_doc_from_json(json, doc_id=doc_id)
 
@@ -796,11 +797,11 @@ class Soledad(object):
         Creating an index will block until the expressions have been evaluated
         and the index generated.
 
-        @param index_name: A unique name which can be used as a key prefix
-        @type index_name: str
-        @param index_expressions: index expressions defining the index
-            information.
-        @type index_expressions: dict
+        :param index_name: A unique name which can be used as a key prefix
+        :type index_name: str
+        :param index_expressions: index expressions defining the index
+                                  information.
+        :type index_expressions: dict
 
             Examples:
 
@@ -816,8 +817,8 @@ class Soledad(object):
         """
         Remove a named index.
 
-        @param index_name: The name of the index we are removing
-        @type index_name: str
+        :param index_name: The name of the index we are removing
+        :type index_name: str
         """
         if self._db:
             return self._db.delete_index(index_name)
@@ -826,8 +827,8 @@ class Soledad(object):
         """
         List the definitions of all known indexes.
 
-        @return: A list of [('index-name', ['field', 'field2'])] definitions.
-        @rtype: list
+        :return: A list of [('index-name', ['field', 'field2'])] definitions.
+        :rtype: list
         """
         if self._db:
             return self._db.list_indexes()
@@ -843,14 +844,14 @@ class Soledad(object):
         It is also possible to append a '*' to the last supplied value (eg
         'val*', '*', '*' or 'val', 'val*', '*', but not 'val*', 'val', '*')
 
-        @param index_name: The index to query
-        @type index_name: str
-        @param key_values: values to match. eg, if you have
-            an index with 3 fields then you would have:
-            get_from_index(index_name, val1, val2, val3)
-        @type key_values: tuple
-        @return: List of [Document]
-        @rtype: list
+        :param index_name: The index to query
+        :type index_name: str
+        :param key_values: values to match. eg, if you have
+                           an index with 3 fields then you would have:
+                           get_from_index(index_name, val1, val2, val3)
+        :type key_values: tuple
+        :return: List of [Document]
+        :rtype: list
         """
         if self._db:
             return self._db.get_from_index(index_name, *key_values)
@@ -869,18 +870,18 @@ class Soledad(object):
         possible to append a '*' to the last supplied value (eg 'val*', '*',
         '*' or 'val', 'val*', '*', but not 'val*', 'val', '*')
 
-        @param index_name: The index to query
-        @type index_name: str
-        @param start_values: tuples of values that define the lower bound of
+        :param index_name: The index to query
+        :type index_name: str
+        :param start_values: tuples of values that define the lower bound of
             the range. eg, if you have an index with 3 fields then you would
             have: (val1, val2, val3)
-        @type start_values: tuple
-        @param end_values: tuples of values that define the upper bound of the
+        :type start_values: tuple
+        :param end_values: tuples of values that define the upper bound of the
             range. eg, if you have an index with 3 fields then you would have:
             (val1, val2, val3)
-        @type end_values: tuple
-        @return: List of [Document]
-        @rtype: list
+        :type end_values: tuple
+        :return: List of [Document]
+        :rtype: list
         """
         if self._db:
             return self._db.get_range_from_index(
@@ -890,10 +891,10 @@ class Soledad(object):
         """
         Return all keys under which documents are indexed in this index.
 
-        @param index_name: The index to query
-        @type index_name: str
-        @return: [] A list of tuples of indexed keys.
-        @rtype: list
+        :param index_name: The index to query
+        :type index_name: str
+        :return: [] A list of tuples of indexed keys.
+        :rtype: list
         """
         if self._db:
             return self._db.get_index_keys(index_name)
@@ -902,11 +903,11 @@ class Soledad(object):
         """
         Get the list of conflicts for the given document.
 
-        @param doc_id: the document id
-        @type doc_id: str
+        :param doc_id: the document id
+        :type doc_id: str
 
-        @return: a list of the document entries that are conflicted
-        @rtype: list
+        :return: a list of the document entries that are conflicted
+        :rtype: list
         """
         if self._db:
             return self._db.get_doc_conflicts(doc_id)
@@ -915,11 +916,11 @@ class Soledad(object):
         """
         Mark a document as no longer conflicted.
 
-        @param doc: a document with the new content to be inserted.
-        @type doc: SoledadDocument
-        @param conflicted_doc_revs: a list of revisions that the new content
-            supersedes.
-        @type conflicted_doc_revs: list
+        :param doc: a document with the new content to be inserted.
+        :type doc: SoledadDocument
+        :param conflicted_doc_revs: a list of revisions that the new content
+                                    supersedes.
+        :type conflicted_doc_revs: list
         """
         if self._db:
             return self._db.resolve_doc(doc, conflicted_doc_revs)
@@ -928,12 +929,12 @@ class Soledad(object):
         """
         Synchronize the local encrypted replica with a remote replica.
 
-        @param url: the url of the target replica to sync with
-        @type url: str
+        :param url: the url of the target replica to sync with
+        :type url: str
 
-        @return: the local generation before the synchronisation was
+        :return: the local generation before the synchronisation was
             performed.
-        @rtype: str
+        :rtype: str
         """
         if self._db:
             local_gen = self._db.sync(
@@ -946,11 +947,11 @@ class Soledad(object):
         """
         Return if local db replica differs from remote url's replica.
 
-        @param url: The remote replica to compare with local replica.
-        @type url: str
+        :param url: The remote replica to compare with local replica.
+        :type url: str
 
-        @return: Whether remote replica and local replica differ.
-        @rtype: bool
+        :return: Whether remote replica and local replica differ.
+        :rtype: bool
         """
         target = SoledadSyncTarget(url, creds=self._creds, crypto=self._crypto)
         info = target.get_sync_info(self._db._get_replica_uid())
@@ -972,8 +973,8 @@ class Soledad(object):
                     'token': '<token>'
             }
 
-        @param token: The authentication token.
-        @type token: str
+        :param token: The authentication token.
+        :type token: str
         """
         self._creds = {
             'token': {
@@ -1004,11 +1005,11 @@ class Soledad(object):
                 self.UUID_KEY: '<uuid>',  # (optional)
             }
 
-        @param include_uuid: Should the uuid be included?
-        @type include_uuid: bool
+        :param include_uuid: Should the uuid be included?
+        :type include_uuid: bool
 
-        @return: The recovery document.
-        @rtype: dict
+        :return: The recovery document.
+        :rtype: dict
         """
         data = {self.STORAGE_SECRETS_KEY: self._secrets}
         if include_uuid:
@@ -1027,8 +1028,8 @@ class Soledad(object):
                 self.UUID_KEY: '<uuid>',  # (optional)
             }
 
-        @param data: The recovery document.
-        @type data: dict
+        :param data: The recovery document.
+        :type data: dict
         """
         # include new secrets in our secret pool.
         for secret_id, secret_data in data[self.STORAGE_SECRETS_KEY].items():
@@ -1101,7 +1102,9 @@ SOLEDAD_TIMEOUT = 10
 
 
 class VerifiedHTTPSConnection(httplib.HTTPSConnection):
-    """HTTPSConnection verifying server side certificates."""
+    """
+    HTTPSConnection verifying server side certificates.
+    """
     # derived from httplib.py
 
     def connect(self):
diff --git a/client/src/leap/soledad/client/auth.py b/client/src/leap/soledad/client/auth.py
index 3cd6dabe..d85e3ba6 100644
--- a/client/src/leap/soledad/client/auth.py
+++ b/client/src/leap/soledad/client/auth.py
@@ -37,10 +37,10 @@ class TokenBasedAuth(object):
         """
         Store given credentials so we can sign the request later.
 
-        @param uuid: The user's uuid.
-        @type uuid: str
-        @param token: The authentication token.
-        @type token: str
+        :param uuid: The user's uuid.
+        :type uuid: str
+        :param token: The authentication token.
+        :type token: str
         """
         self._creds = {'token': (uuid, token)}
 
@@ -51,15 +51,15 @@ class TokenBasedAuth(object):
 
             [('Authorization', 'Token <base64 encoded creds')]
 
-        @param method: The HTTP method.
-        @type method: str
-        @param url_query: The URL query string.
-        @type url_query: str
-        @param params: A list with encoded query parameters.
-        @type param: list
+        :param method: The HTTP method.
+        :type method: str
+        :param url_query: The URL query string.
+        :type url_query: str
+        :param params: A list with encoded query parameters.
+        :type param: list
 
-        @return: The Authorization header.
-        @rtype: list of tuple
+        :return: The Authorization header.
+        :rtype: list of tuple
         """
         if 'token' in self._creds:
             uuid, token = self._creds['token']
diff --git a/client/src/leap/soledad/client/crypto.py b/client/src/leap/soledad/client/crypto.py
index 9fcff8e9..a6372107 100644
--- a/client/src/leap/soledad/client/crypto.py
+++ b/client/src/leap/soledad/client/crypto.py
@@ -70,8 +70,8 @@ class SoledadCrypto(object):
         """
         Initialize the crypto object.
 
-        @param soledad: A Soledad instance for key lookup.
-        @type soledad: leap.soledad.Soledad
+        :param soledad: A Soledad instance for key lookup.
+        :type soledad: leap.soledad.Soledad
         """
         self._soledad = soledad
 
@@ -82,15 +82,15 @@ class SoledadCrypto(object):
 
         Currently, the only  encryption method supported is AES-256 CTR mode.
 
-        @param data: The data to be encrypted.
-        @type data: str
-        @param key: The key used to encrypt C{data} (must be 256 bits long).
-        @type key: str
-        @param method: The encryption method to use.
-        @type method: str
+        :param data: The data to be encrypted.
+        :type data: str
+        :param key: The key used to encrypt C{data} (must be 256 bits long).
+        :type key: str
+        :param method: The encryption method to use.
+        :type method: str
 
-        @return: A tuple with the initial value and the encrypted data.
-        @rtype: (long, str)
+        :return: A tuple with the initial value and the encrypted data.
+        :rtype: (long, str)
         """
         soledad_assert_type(key, str)
 
@@ -119,17 +119,17 @@ class SoledadCrypto(object):
 
         Currently, the only encryption method supported is AES-256 CTR mode.
 
-        @param data: The data to be decrypted.
-        @type data: str
-        @param key: The key used to decrypt C{data} (must be 256 bits long).
-        @type key: str
-        @param method: The encryption method to use.
-        @type method: str
-        @param kwargs: Other parameters specific to each encryption method.
-        @type kwargs: dict
-
-        @return: The decrypted data.
-        @rtype: str
+        :param data: The data to be decrypted.
+        :type data: str
+        :param key: The key used to decrypt C{data} (must be 256 bits long).
+        :type key: str
+        :param method: The encryption method to use.
+        :type method: str
+        :param kwargs: Other parameters specific to each encryption method.
+        :type kwargs: dict
+
+        :return: The decrypted data.
+        :rtype: str
         """
         soledad_assert_type(key, str)
         # assert params
@@ -160,14 +160,14 @@ class SoledadCrypto(object):
         secret stripped from the first MAC_KEY_LENGTH characters. The HMAC
         message is C{doc_id}.
 
-        @param doc_id: The id of the document that will be encrypted using
+        :param doc_id: The id of the document that will be encrypted using
             this passphrase.
-        @type doc_id: str
+        :type doc_id: str
 
-        @return: The passphrase.
-        @rtype: str
+        :return: The passphrase.
+        :rtype: str
 
-        @raise NoSymmetricSecret: if no symmetric secret was supplied.
+        :raise NoSymmetricSecret: if no symmetric secret was supplied.
         """
         if self.secret is None:
             raise NoSymmetricSecret()
@@ -187,13 +187,13 @@ class SoledadCrypto(object):
         function. The key used for HMAC is the first MAC_KEY_LENGTH characters
         of Soledad's storage secret. The HMAC message is C{doc_id}.
 
-        @param doc_id: The id of the document.
-        @type doc_id: str
+        :param doc_id: The id of the document.
+        :type doc_id: str
 
-        @return: The key.
-        @rtype: str
+        :return: The key.
+        :rtype: str
 
-        @raise NoSymmetricSecret: if no symmetric secret was supplied.
+        :raise NoSymmetricSecret: if no symmetric secret was supplied.
         """
         if self.secret is None:
             raise NoSymmetricSecret()
diff --git a/client/src/leap/soledad/client/shared_db.py b/client/src/leap/soledad/client/shared_db.py
index a6ca504d..adcde4e2 100644
--- a/client/src/leap/soledad/client/shared_db.py
+++ b/client/src/leap/soledad/client/shared_db.py
@@ -61,10 +61,10 @@ class SoledadSharedDatabase(http_database.HTTPDatabase, TokenBasedAuth):
         """
         Store given credentials so we can sign the request later.
 
-        @param uuid: The user's uuid.
-        @type uuid: str
-        @param token: The authentication token.
-        @type token: str
+        :param uuid: The user's uuid.
+        :type uuid: str
+        :param token: The authentication token.
+        :type token: str
         """
         TokenBasedAuth.set_token_credentials(self, uuid, token)
 
@@ -72,15 +72,15 @@ class SoledadSharedDatabase(http_database.HTTPDatabase, TokenBasedAuth):
         """
         Return an authorization header to be included in the HTTP request.
 
-        @param method: The HTTP method.
-        @type method: str
-        @param url_query: The URL query string.
-        @type url_query: str
-        @param params: A list with encoded query parameters.
-        @type param: list
+        :param method: The HTTP method.
+        :type method: str
+        :param url_query: The URL query string.
+        :type url_query: str
+        :param params: A list with encoded query parameters.
+        :type param: list
 
-        @return: The Authorization header.
-        @rtype: list of tuple
+        :return: The Authorization header.
+        :rtype: list of tuple
         """
         return TokenBasedAuth._sign_request(self, method, url_query, params)
 
@@ -95,16 +95,16 @@ class SoledadSharedDatabase(http_database.HTTPDatabase, TokenBasedAuth):
         """
         Open a Soledad shared database.
 
-        @param url: URL of the remote database.
-        @type url: str
-        @param create: Should the database be created if it does not already
+        :param url: URL of the remote database.
+        :type url: str
+        :param create: Should the database be created if it does not already
             exist?
-        @type create: bool
-        @param token: An authentication token for accessing the shared db.
-        @type token: str
+        :type create: bool
+        :param token: An authentication token for accessing the shared db.
+        :type token: str
 
-        @return: The shared database in the given url.
-        @rtype: SoledadSharedDatabase
+        :return: The shared database in the given url.
+        :rtype: SoledadSharedDatabase
         """
         db = SoledadSharedDatabase(url, creds=creds)
         db.open(create)
@@ -115,10 +115,10 @@ class SoledadSharedDatabase(http_database.HTTPDatabase, TokenBasedAuth):
         """
         Dummy method that prevents from deleting shared database.
 
-        @raise: This will always raise an Unauthorized exception.
+        :raise: This will always raise an Unauthorized exception.
 
-        @param url: The database URL.
-        @type url: str
+        :param url: The database URL.
+        :type url: str
         """
         raise Unauthorized("Can't delete shared database.")
 
@@ -126,13 +126,13 @@ class SoledadSharedDatabase(http_database.HTTPDatabase, TokenBasedAuth):
         """
         Initialize database with auth token and encryption powers.
 
-        @param url: URL of the remote database.
-        @type url: str
-        @param document_factory: A factory for U1BD documents.
-        @type document_factory: u1db.Document
-        @param creds: A tuple containing the authentication method and
+        :param url: URL of the remote database.
+        :type url: str
+        :param document_factory: A factory for U1BD documents.
+        :type document_factory: u1db.Document
+        :param creds: A tuple containing the authentication method and
             credentials.
-        @type creds: tuple
+        :type creds: tuple
         """
         http_database.HTTPDatabase.__init__(self, url, document_factory,
                                             creds)
diff --git a/client/src/leap/soledad/client/sqlcipher.py b/client/src/leap/soledad/client/sqlcipher.py
index c605c28c..3e01a4fb 100644
--- a/client/src/leap/soledad/client/sqlcipher.py
+++ b/client/src/leap/soledad/client/sqlcipher.py
@@ -79,29 +79,29 @@ def open(path, password, create=True, document_factory=None, crypto=None,
     Will raise u1db.errors.DatabaseDoesNotExist if create=False and the
     database does not already exist.
 
-    @param path: The filesystem path for the database to open.
-    @param type: str
-    @param create: True/False, should the database be created if it doesn't
+    :param path: The filesystem path for the database to open.
+    :param type: str
+    :param create: True/False, should the database be created if it doesn't
         already exist?
-    @param type: bool
-    @param document_factory: A function that will be called with the same
+    :param type: bool
+    :param document_factory: A function that will be called with the same
         parameters as Document.__init__.
-    @type document_factory: callable
-    @param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
+    :type document_factory: callable
+    :param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
         document contents when syncing.
-    @type crypto: soledad.crypto.SoledadCrypto
-    @param raw_key: Whether C{password} is a raw 64-char hex string or a
+    :type crypto: soledad.crypto.SoledadCrypto
+    :param raw_key: Whether C{password} is a raw 64-char hex string or a
         passphrase that should be hashed to obtain the encyrption key.
-    @type raw_key: bool
-    @param cipher: The cipher and mode to use.
-    @type cipher: str
-    @param kdf_iter: The number of iterations to use.
-    @type kdf_iter: int
-    @param cipher_page_size: The page size.
-    @type cipher_page_size: int
-
-    @return: An instance of Database.
-    @rtype SQLCipherDatabase
+    :type raw_key: bool
+    :param cipher: The cipher and mode to use.
+    :type cipher: str
+    :param kdf_iter: The number of iterations to use.
+    :type kdf_iter: int
+    :param cipher_page_size: The page size.
+    :type cipher_page_size: int
+
+    :return: An instance of Database.
+    :rtype SQLCipherDatabase
     """
     return SQLCipherDatabase.open_database(
         path, password, create=create, document_factory=document_factory,
@@ -143,25 +143,25 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Create a new sqlcipher file.
 
-        @param sqlcipher_file: The path for the SQLCipher file.
-        @type sqlcipher_file: str
-        @param password: The password that protects the SQLCipher db.
-        @type password: str
-        @param document_factory: A function that will be called with the same
+        :param sqlcipher_file: The path for the SQLCipher file.
+        :type sqlcipher_file: str
+        :param password: The password that protects the SQLCipher db.
+        :type password: str
+        :param document_factory: A function that will be called with the same
             parameters as Document.__init__.
-        @type document_factory: callable
-        @param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
+        :type document_factory: callable
+        :param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
             document contents when syncing.
-        @type crypto: soledad.crypto.SoledadCrypto
-        @param raw_key: Whether C{password} is a raw 64-char hex string or a
+        :type crypto: soledad.crypto.SoledadCrypto
+        :param raw_key: Whether C{password} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
-        @param cipher: The cipher and mode to use.
-        @type cipher: str
-        @param kdf_iter: The number of iterations to use.
-        @type kdf_iter: int
-        @param cipher_page_size: The page size.
-        @type cipher_page_size: int
+        :type raw_key: bool
+        :param cipher: The cipher and mode to use.
+        :type cipher: str
+        :param kdf_iter: The number of iterations to use.
+        :type kdf_iter: int
+        :param cipher_page_size: The page size.
+        :type cipher_page_size: int
         """
         # ensure the db is encrypted if the file already exists
         if os.path.exists(sqlcipher_file):
@@ -195,28 +195,28 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Open a SQLCipher database.
 
-        @param sqlcipher_file: The path for the SQLCipher file.
-        @type sqlcipher_file: str
-        @param password: The password that protects the SQLCipher db.
-        @type password: str
-        @param document_factory: A function that will be called with the same
+        :param sqlcipher_file: The path for the SQLCipher file.
+        :type sqlcipher_file: str
+        :param password: The password that protects the SQLCipher db.
+        :type password: str
+        :param document_factory: A function that will be called with the same
             parameters as Document.__init__.
-        @type document_factory: callable
-        @param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
+        :type document_factory: callable
+        :param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
             document contents when syncing.
-        @type crypto: soledad.crypto.SoledadCrypto
-        @param raw_key: Whether C{password} is a raw 64-char hex string or a
+        :type crypto: soledad.crypto.SoledadCrypto
+        :param raw_key: Whether C{password} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
-        @param cipher: The cipher and mode to use.
-        @type cipher: str
-        @param kdf_iter: The number of iterations to use.
-        @type kdf_iter: int
-        @param cipher_page_size: The page size.
-        @type cipher_page_size: int
+        :type raw_key: bool
+        :param cipher: The cipher and mode to use.
+        :type cipher: str
+        :param kdf_iter: The number of iterations to use.
+        :type kdf_iter: int
+        :param cipher_page_size: The page size.
+        :type cipher_page_size: int
 
-        @return: The database object.
-        @rtype: SQLCipherDatabase
+        :return: The database object.
+        :rtype: SQLCipherDatabase
         """
         if not os.path.isfile(sqlcipher_file):
             raise u1db_errors.DatabaseDoesNotExist()
@@ -267,33 +267,33 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Open a SQLCipher database.
 
-        @param sqlcipher_file: The path for the SQLCipher file.
-        @type sqlcipher_file: str
-        @param password: The password that protects the SQLCipher db.
-        @type password: str
-        @param create: Should the datbase be created if it does not already
+        :param sqlcipher_file: The path for the SQLCipher file.
+        :type sqlcipher_file: str
+        :param password: The password that protects the SQLCipher db.
+        :type password: str
+        :param create: Should the datbase be created if it does not already
             exist?
-        @type: bool
-        @param backend_cls: A class to use as backend.
-        @type backend_cls: type
-        @param document_factory: A function that will be called with the same
+        :type: bool
+        :param backend_cls: A class to use as backend.
+        :type backend_cls: type
+        :param document_factory: A function that will be called with the same
             parameters as Document.__init__.
-        @type document_factory: callable
-        @param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
+        :type document_factory: callable
+        :param crypto: An instance of SoledadCrypto so we can encrypt/decrypt
             document contents when syncing.
-        @type crypto: soledad.crypto.SoledadCrypto
-        @param raw_key: Whether C{password} is a raw 64-char hex string or a
+        :type crypto: soledad.crypto.SoledadCrypto
+        :param raw_key: Whether C{password} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
-        @param cipher: The cipher and mode to use.
-        @type cipher: str
-        @param kdf_iter: The number of iterations to use.
-        @type kdf_iter: int
-        @param cipher_page_size: The page size.
-        @type cipher_page_size: int
+        :type raw_key: bool
+        :param cipher: The cipher and mode to use.
+        :type cipher: str
+        :param kdf_iter: The number of iterations to use.
+        :type kdf_iter: int
+        :param cipher_page_size: The page size.
+        :type cipher_page_size: int
 
-        @return: The database object.
-        @rtype: SQLCipherDatabase
+        :return: The database object.
+        :rtype: SQLCipherDatabase
         """
         try:
             return cls._open_database(
@@ -316,16 +316,16 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Synchronize documents with remote replica exposed at url.
 
-        @param url: The url of the target replica to sync with.
-        @type url: str
-        @param creds: optional dictionary giving credentials.
+        :param url: The url of the target replica to sync with.
+        :type url: str
+        :param creds: optional dictionary giving credentials.
             to authorize the operation with the server.
-        @type creds: dict
-        @param autocreate: Ask the target to create the db if non-existent.
-        @type autocreate: bool
+        :type creds: dict
+        :param autocreate: Ask the target to create the db if non-existent.
+        :type autocreate: bool
 
-        @return: The local generation before the synchronisation was performed.
-        @rtype: int
+        :return: The local generation before the synchronisation was performed.
+        :rtype: int
         """
         from u1db.sync import Synchronizer
         from leap.soledad.client.target import SoledadSyncTarget
@@ -343,8 +343,8 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         method, which is executed when the database schema is created. Here,
         we use it to include the "syncable" property for LeapDocuments.
 
-        @param c: The cursor for querying the database.
-        @type c: dbapi2.cursor
+        :param c: The cursor for querying the database.
+        :type c: dbapi2.cursor
         """
         c.execute(
             'ALTER TABLE document '
@@ -354,10 +354,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Update a document and all indexes related to it.
 
-        @param old_doc: The old version of the document.
-        @type old_doc: u1db.Document
-        @param doc: The new version of the document.
-        @type doc: u1db.Document
+        :param old_doc: The old version of the document.
+        :type old_doc: u1db.Document
+        :param doc: The new version of the document.
+        :type doc: u1db.Document
         """
         sqlite_backend.SQLitePartialExpandDatabase._put_and_update_indexes(
             self, old_doc, doc)
@@ -370,15 +370,15 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         """
         Get just the document content, without fancy handling.
 
-        @param doc_id: The unique document identifier
-        @type doc_id: str
-        @param include_deleted: If set to True, deleted documents will be
+        :param doc_id: The unique document identifier
+        :type doc_id: str
+        :param include_deleted: If set to True, deleted documents will be
             returned with empty content. Otherwise asking for a deleted
             document will return None.
-        @type include_deleted: bool
+        :type include_deleted: bool
 
-        @return: a Document object.
-        @type: u1db.Document
+        :return: a Document object.
+        :type: u1db.Document
         """
         doc = sqlite_backend.SQLitePartialExpandDatabase._get_doc(
             self, doc_id, check_for_conflicts)
@@ -411,19 +411,19 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         which will attempt to read the first page of the database and will
         parse the schema.
 
-        @param sqlcipher_file: The path for the SQLCipher file.
-        @type sqlcipher_file: str
-        @param key: The key that protects the SQLCipher db.
-        @type key: str
-        @param raw_key: Whether C{key} is a raw 64-char hex string or a
+        :param sqlcipher_file: The path for the SQLCipher file.
+        :type sqlcipher_file: str
+        :param key: The key that protects the SQLCipher db.
+        :type key: str
+        :param raw_key: Whether C{key} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
-        @param cipher: The cipher and mode to use.
-        @type cipher: str
-        @param kdf_iter: The number of iterations to use.
-        @type kdf_iter: int
-        @param cipher_page_size: The page size.
-        @type cipher_page_size: int
+        :type raw_key: bool
+        :param cipher: The cipher and mode to use.
+        :type cipher: str
+        :param kdf_iter: The number of iterations to use.
+        :type kdf_iter: int
+        :param cipher_page_size: The page size.
+        :type cipher_page_size: int
         """
         try:
             # try to open an encrypted database with the regular u1db
@@ -473,11 +473,11 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         * PRAGMA key should generally be called as the first operation on a
           database.
 
-        @param key: The key for use with the database.
-        @type key: str
-        @param raw_key: Whether C{key} is a raw 64-char hex string or a
+        :param key: The key for use with the database.
+        :type key: str
+        :param raw_key: Whether C{key} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
+        :type raw_key: bool
         """
         if raw_key:
             cls._pragma_key_raw(db_handle, key)
@@ -495,10 +495,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         if you want to do so you should use a raw key instead and derive the
         key using your own KDF.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param passphrase: The passphrase used to derive the encryption key.
-        @type passphrase: str
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param passphrase: The passphrase used to derive the encryption key.
+        :type passphrase: str
         """
         db_handle.cursor().execute("PRAGMA key = '%s'" % passphrase)
 
@@ -512,10 +512,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         ensure that the data provided is a 64 character hex string, which will
         be converted directly to 32 bytes (256 bits) of key data.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param key: A 64 character hex string.
-        @type key: str
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param key: A 64 character hex string.
+        :type key: str
         """
         if not all(c in string.hexdigits for c in key):
             raise NotAnHexString(key)
@@ -546,10 +546,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
           widely available and peer-reviewed OpenSSL libcrypto for all
           cryptographic functions.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param cipher: The cipher and mode to use.
-        @type cipher: str
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param cipher: The cipher and mode to use.
+        :type cipher: str
         """
         db_handle.cursor().execute("PRAGMA cipher = '%s'" % cipher)
 
@@ -575,10 +575,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         * It is not recommended to reduce the number of iterations if a
           passphrase is in use.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param kdf_iter: The number of iterations to use.
-        @type kdf_iter: int
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param kdf_iter: The number of iterations to use.
+        :type kdf_iter: int
         """
         db_handle.cursor().execute("PRAGMA kdf_iter = '%d'" % kdf_iter)
 
@@ -608,10 +608,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         * If a non-default value is used PRAGMA cipher_page_size to create a
           database, it must also be called every time that database is opened.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param cipher_page_size: The page size.
-        @type cipher_page_size: int
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param cipher_page_size: The page size.
+        :type cipher_page_size: int
         """
         db_handle.cursor().execute(
             "PRAGMA cipher_page_size = '%d'" % cipher_page_size)
@@ -637,13 +637,13 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
           code>PRAGMA rekey_kdf_iter. These are deprecated and should not be
           used. Instead, use sqlcipher_export().
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param new_key: The new key.
-        @type new_key: str
-        @param raw_key: Whether C{password} is a raw 64-char hex string or a
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param new_key: The new key.
+        :type new_key: str
+        :param raw_key: Whether C{password} is a raw 64-char hex string or a
             passphrase that should be hashed to obtain the encyrption key.
-        @type raw_key: bool
+        :type raw_key: bool
         """
         if raw_key:
             cls._pragma_rekey_raw(db_handle, key)
@@ -659,10 +659,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         PBKDF2 key derivation. The result is used as the encryption key for
         the database.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param passphrase: The passphrase used to derive the encryption key.
-        @type passphrase: str
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param passphrase: The passphrase used to derive the encryption key.
+        :type passphrase: str
         """
         db_handle.cursor().execute("PRAGMA rekey = '%s'" % passphrase)
 
@@ -676,10 +676,10 @@ class SQLCipherDatabase(sqlite_backend.SQLitePartialExpandDatabase):
         ensure that the data provided is a 64 character hex string, which will
         be converted directly to 32 bytes (256 bits) of key data.
 
-        @param db_handle: A handle to the SQLCipher database.
-        @type db_handle: pysqlcipher.Connection
-        @param key: A 64 character hex string.
-        @type key: str
+        :param db_handle: A handle to the SQLCipher database.
+        :type db_handle: pysqlcipher.Connection
+        :param key: A 64 character hex string.
+        :type key: str
         """
         if not all(c in string.hexdigits for c in key):
             raise NotAnHexString(key)
diff --git a/client/src/leap/soledad/client/target.py b/client/src/leap/soledad/client/target.py
index d0bc3706..65639887 100644
--- a/client/src/leap/soledad/client/target.py
+++ b/client/src/leap/soledad/client/target.py
@@ -98,19 +98,19 @@ def mac_doc(crypto, doc_id, doc_rev, ciphertext, mac_method):
         * msg: doc_id + doc_rev + ciphertext
         * digestmod: sha256
 
-    @param crypto: A SoledadCryto instance used to perform the encryption.
-    @type crypto: leap.soledad.crypto.SoledadCrypto
-    @param doc_id: The id of the document.
-    @type doc_id: str
-    @param doc_rev: The revision of the document.
-    @type doc_rev: str
-    @param ciphertext: The content of the document.
-    @type ciphertext: str
-    @param mac_method: The MAC method to use.
-    @type mac_method: str
-
-    @return: The calculated MAC.
-    @rtype: str
+    :param crypto: A SoledadCryto instance used to perform the encryption.
+    :type crypto: leap.soledad.crypto.SoledadCrypto
+    :param doc_id: The id of the document.
+    :type doc_id: str
+    :param doc_rev: The revision of the document.
+    :type doc_rev: str
+    :param ciphertext: The content of the document.
+    :type ciphertext: str
+    :param mac_method: The MAC method to use.
+    :type mac_method: str
+
+    :return: The calculated MAC.
+    :rtype: str
     """
     if mac_method == MacMethods.HMAC:
         return hmac.new(
@@ -137,14 +137,14 @@ def encrypt_doc(crypto, doc):
             MAC_METHOD_KEY: 'hmac'
         }
 
-    @param crypto: A SoledadCryto instance used to perform the encryption.
-    @type crypto: leap.soledad.crypto.SoledadCrypto
-    @param doc: The document with contents to be encrypted.
-    @type doc: SoledadDocument
+    :param crypto: A SoledadCryto instance used to perform the encryption.
+    :type crypto: leap.soledad.crypto.SoledadCrypto
+    :param doc: The document with contents to be encrypted.
+    :type doc: SoledadDocument
 
-    @return: The JSON serialization of the dict representing the encrypted
+    :return: The JSON serialization of the dict representing the encrypted
         content.
-    @rtype: str
+    :rtype: str
     """
     soledad_assert(doc.is_tombstone() is False)
     # encrypt content using AES-256 CTR mode
@@ -191,13 +191,13 @@ def decrypt_doc(crypto, doc):
     EncryptionSchemes.SYMKEY and C{enc_method} is
     EncryptionMethods.AES_256_CTR.
 
-    @param crypto: A SoledadCryto instance to perform the encryption.
-    @type crypto: leap.soledad.crypto.SoledadCrypto
-    @param doc: The document to be decrypted.
-    @type doc: SoledadDocument
+    :param crypto: A SoledadCryto instance to perform the encryption.
+    :type crypto: leap.soledad.crypto.SoledadCrypto
+    :param doc: The document to be decrypted.
+    :type doc: SoledadDocument
 
-    @return: The JSON serialization of the decrypted content.
-    @rtype: str
+    :return: The JSON serialization of the decrypted content.
+    :rtype: str
     """
     soledad_assert(doc.is_tombstone() is False)
     soledad_assert(ENC_JSON_KEY in doc.content)
@@ -258,10 +258,10 @@ class SoledadSyncTarget(HTTPSyncTarget, TokenBasedAuth):
         """
         Store given credentials so we can sign the request later.
 
-        @param uuid: The user's uuid.
-        @type uuid: str
-        @param token: The authentication token.
-        @type token: str
+        :param uuid: The user's uuid.
+        :type uuid: str
+        :param token: The authentication token.
+        :type token: str
         """
         TokenBasedAuth.set_token_credentials(self, uuid, token)
 
@@ -269,15 +269,15 @@ class SoledadSyncTarget(HTTPSyncTarget, TokenBasedAuth):
         """
         Return an authorization header to be included in the HTTP request.
 
-        @param method: The HTTP method.
-        @type method: str
-        @param url_query: The URL query string.
-        @type url_query: str
-        @param params: A list with encoded query parameters.
-        @type param: list
+        :param method: The HTTP method.
+        :type method: str
+        :param url_query: The URL query string.
+        :type url_query: str
+        :param params: A list with encoded query parameters.
+        :type param: list
 
-        @return: The Authorization header.
-        @rtype: list of tuple
+        :return: The Authorization header.
+        :rtype: list of tuple
         """
         return TokenBasedAuth._sign_request(self, method, url_query, params)
 
@@ -293,14 +293,14 @@ class SoledadSyncTarget(HTTPSyncTarget, TokenBasedAuth):
         """
         Initialize the SoledadSyncTarget.
 
-        @param url: The url of the target replica to sync with.
-        @type url: str
-        @param creds: optional dictionary giving credentials.
+        :param url: The url of the target replica to sync with.
+        :type url: str
+        :param creds: optional dictionary giving credentials.
             to authorize the operation with the server.
-        @type creds: dict
-        @param soledad: An instance of Soledad so we can encrypt/decrypt
+        :type creds: dict
+        :param soledad: An instance of Soledad so we can encrypt/decrypt
             document contents when syncing.
-        @type soledad: soledad.Soledad
+        :type soledad: soledad.Soledad
         """
         HTTPSyncTarget.__init__(self, url, creds)
         self._crypto = crypto
@@ -314,19 +314,19 @@ class SoledadSyncTarget(HTTPSyncTarget, TokenBasedAuth):
         EncryptionSchemes.SYMKEY, then this method will decrypt it with
         Soledad's symmetric key.
 
-        @param data: The body of the HTTP response.
-        @type data: str
-        @param return_doc_cb: A callback to insert docs from target.
-        @type return_doc_cb: function
-        @param ensure_callback: A callback to ensure we have the correct
+        :param data: The body of the HTTP response.
+        :type data: str
+        :param return_doc_cb: A callback to insert docs from target.
+        :type return_doc_cb: function
+        :param ensure_callback: A callback to ensure we have the correct
             target_replica_uid, if it was just created.
-        @type ensure_callback: function
+        :type ensure_callback: function
 
-        @raise BrokenSyncStream: If C{data} is malformed.
+        :raise BrokenSyncStream: If C{data} is malformed.
 
-        @return: A dictionary representing the first line of the response got
+        :return: A dictionary representing the first line of the response got
             from remote replica.
-        @rtype: list of str
+        :rtype: list of str
         """
         parts = data.splitlines()  # one at a time
         if not parts or parts[0] != '[':
@@ -381,25 +381,25 @@ class SoledadSyncTarget(HTTPSyncTarget, TokenBasedAuth):
         This does the same as the parent's method but encrypts content before
         syncing.
 
-        @param docs_by_generations: A list of (doc_id, generation, trans_id)
+        :param docs_by_generations: A list of (doc_id, generation, trans_id)
             of local documents that were changed since the last local
             generation the remote replica knows about.
-        @type docs_by_generations: list of tuples
-        @param source_replica_uid: The uid of the source replica.
-        @type source_replica_uid: str
-        @param last_known_generation: Target's last known generation.
-        @type last_known_generation: int
-        @param last_known_trans_id: Target's last known transaction id.
-        @type last_known_trans_id: str
-        @param return_doc_cb: A callback for inserting received documents from
+        :type docs_by_generations: list of tuples
+        :param source_replica_uid: The uid of the source replica.
+        :type source_replica_uid: str
+        :param last_known_generation: Target's last known generation.
+        :type last_known_generation: int
+        :param last_known_trans_id: Target's last known transaction id.
+        :type last_known_trans_id: str
+        :param return_doc_cb: A callback for inserting received documents from
             target.
-        @type return_doc_cb: function
-        @param ensure_callback: A callback that ensures we know the target
+        :type return_doc_cb: function
+        :param ensure_callback: A callback that ensures we know the target
             replica uid if the target replica was just created.
-        @type ensure_callback: function
+        :type ensure_callback: function
 
-        @return: The new generation and transaction id of the target replica.
-        @rtype: tuple
+        :return: The new generation and transaction id of the target replica.
+        :rtype: tuple
         """
         self._ensure_connection()
         if self._trace_hook:  # for tests