[docs] fix typos and improve text from code review

3 files changed, 15 insertions, 13 deletions

diff --git a/src/leap/soledad/client/_db/blobs.py b/src/leap/soledad/client/_db/blobs.py
index 5334ffe5..3bbbb1e5 100644
--- a/src/leap/soledad/client/_db/blobs.py
+++ b/src/leap/soledad/client/_db/blobs.py
@@ -137,6 +137,9 @@ class DecrypterBuffer(object):
                 tag=self.tag)
             return TruncatedTailPipe(self.decrypter, tail_size=len(self.tag))
         except EncryptionSchemeNotImplementedException:
+            # If we do not support the provided encryption scheme, than that's
+            # something for the application using soledad to handle. This is
+            # the case on asymmetrically encrypted documents on IncomingBox.
             self.raw_data = BytesIO()
             return self.raw_data
 
diff --git a/src/leap/soledad/client/incoming.py b/src/leap/soledad/client/incoming.py
index 58e0885b..879684e8 100644
--- a/src/leap/soledad/client/incoming.py
+++ b/src/leap/soledad/client/incoming.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # incoming.py
-# Copyright (C) 2014 LEAP
+# Copyright (C) 2017 LEAP
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -118,10 +118,9 @@ class IncomingBox:
     @defer.inlineCallbacks
     def fetch_for_processing(self, blob_id):
         """
-        Try to flag a blob as PROCESSING, if server allows (no other replica
-        with it), then it gets reserved and fetched. Otherwise `None` is
-        returned, making the loop skip this item as another replica reserved it
-        already.
+        Try to reserve a blob (by flagging it as PROCESSING) and then fetch it.
+        If it is already reserved by another replica, return `None` causing the
+        loop to skip this item.
         :param blob_id: Unique identifier of a blob.
         :type blob_id: str
         :return: A deferred that fires when operation finishes.
@@ -133,7 +132,7 @@ class IncomingBox:
             yield self.blob_manager.set_flags(blob_id, [Flags.PROCESSED],
                                               namespace=self.namespace)
         except:
-            defer.returnValue([])
+            defer.returnValue(None)
         blob = yield self.blob_manager.get(blob_id, namespace=self.namespace)
         defer.returnValue(blob)
 
@@ -149,7 +148,7 @@ class IncomingBox:
 
     def set_processed(self, blob_id):
         """
-        Flag a blob as Flags.FAILED
+        Flag a blob with Flags.PROCESSED
         :param blob_id: Unique identifier of a blob.
         :type blob_id: str
         :return: A deferred that fires when operation finishes.
@@ -160,7 +159,7 @@ class IncomingBox:
 
     def set_failed(self, blob_id):
         """
-        Flag a blob as Flags.FAILED
+        Flag a blob with Flags.FAILED
         :param blob_id: Unique identifier of a blob.
         :type blob_id: str
         :return: A deferred that fires when operation finishes.
diff --git a/src/leap/soledad/client/interfaces.py b/src/leap/soledad/client/interfaces.py
index 25a7130f..4b6beb8d 100644
--- a/src/leap/soledad/client/interfaces.py
+++ b/src/leap/soledad/client/interfaces.py
@@ -375,16 +375,16 @@ class IIncomingBoxConsumer(Interface):
     Note that processing and saving are separated from each other. That's
     important for error handling on Soledad side as saving has side effects
     while processing doesn't, so we can always retry processing while retrying
-    to save is risky.
+    persistence is risky.
     Remember that on multiple devices scenario a replica that fails processing
-    of an item can give it to another replica retry, as long as there are no
+    of an item can give up to another replica retry, as long as there are no
     side effects from processing.
     """
     name = Attribute("Consumer name, for readable error logging")
 
     def process(self, item, item_id, encrypted=True):
         """
-        This method process an incoming box item.
+        This method processes an incoming box item.
         :param item: Incoming box item data
         :type item: file-like object
         :param item_id: Unique identifier of the item being processed.
@@ -397,7 +397,7 @@ class IIncomingBoxConsumer(Interface):
         :return:
             A deferred that fires with a list of parts to be delivered to
             `save` function. This list type should match `save` method `parts`
-            parameter. It is implementation dependant.
+            parameter. It is implementation dependent.
         :rtype: Deferred
         """
 
@@ -405,7 +405,7 @@ class IIncomingBoxConsumer(Interface):
         """
         This method persists resulting items from processing.
         :param parts: resulting parts from processing
-        :type parts: Implementation dependant.
+        :type parts: Implementation dependent.
         :param item_id: Unique identifier of the item being processed.
         :type item_id: str
         :return: