Update outdated or incorrect docstrings (#748)

bigchaindb/commands/utils.py

@@ -19,14 +19,9 @@ def start_rethinkdb():
     """Start RethinkDB as a child process and wait for it to be
     available.
 
-    Args:
-        wait_for_db (bool): wait for the database to be ready
-        extra_opts (list): a list of extra options to be used when
-            starting the db
-
     Raises:
-        ``bigchaindb.common.exceptions.StartupError`` if RethinkDB cannot
-        be started.
+        :class:`~bigchaindb.common.exceptions.StartupError` if
+            RethinkDB cannot be started.
     """
 
     proc = subprocess.Popen(['rethinkdb', '--bind', 'all'],

bigchaindb/core.py

@@ -198,10 +198,10 @@ class Bigchain(object):
                                    the return value is then a tuple: (tx, status)
 
         Returns:
-            A dict with the transaction details if the transaction was found.
-            Will add the transaction status to payload ('valid', 'undecided',
-            or 'backlog'). If no transaction with that `txid` was found it
-            returns `None`
+            A :class:`~.models.Transaction` instance if the transaction
+            was found, otherwise ``None``.
+            If :attr:`include_status` is ``True``, also returns the
+            transaction's status if the transaction was found.
         """
 
         response, tx_status = None, None
@@ -412,14 +412,14 @@ class Bigchain(object):
             return None
 
     def get_owned_ids(self, owner):
-        """Retrieve a list of `txids` that can we used has inputs.
+        """Retrieve a list of `txid`s that can be used as inputs.
 
         Args:
             owner (str): base58 encoded public key.
 
         Returns:
-            list (TransactionLink): list of `txid`s and `cid`s pointing to
-                                      another transaction's condition
+            :obj:`list` of TransactionLink: list of `txid`s and `cid`s
+            pointing to another transaction's condition
         """
 
         # get all transactions in which owner is in the `owners_after` list
@@ -587,11 +587,11 @@ class Bigchain(object):
         return block
 
     def vote(self, block_id, previous_block_id, decision, invalid_reason=None):
-        """Cast your vote on the block given the previous_block_hash and the decision (valid/invalid)
-        return the block to the updated in the database.
+        """Create a signed vote for a block given the
+		:attr:`previous_block_id` and the :attr:`decision` (valid/invalid).
 
         Args:
-            block_id (str): The id of the block to vote.
+            block_id (str): The id of the block to vote on.
             previous_block_id (str): The id of the previous block.
             decision (bool): Whether the block is valid or invalid.
             invalid_reason (Optional[str]): Reason the block is invalid

bigchaindb/pipelines/stale.py

@@ -26,8 +26,8 @@ class StaleTransactionMonitor:
         Args:
             timeout: how often to check for stale tx (in sec)
             backlog_reassign_delay: How stale a transaction should
-            be before reassignment (in sec). If supplied, overrides the
-            Bigchain default value.
+                be before reassignment (in sec). If supplied, overrides
+                the Bigchain default value.
         """
         self.bigchain = Bigchain(backlog_reassign_delay=backlog_reassign_delay)
         self.timeout = timeout

bigchaindb/pipelines/utils.py

@@ -13,16 +13,16 @@ logger = logging.getLogger(__name__)
 
 
 class ChangeFeed(Node):
-    """This class wraps a RethinkDB changefeed adding a `prefeed`.
+    """This class wraps a RethinkDB changefeed adding a ``prefeed``.
 
-    It extends the ``multipipes::Node`` class to make it pluggable in
-    other Pipelines instances, and it makes usage of ``self.outqueue``
-    to output the data.
+    It extends :class:`multipipes.Node` to make it pluggable in other
+    Pipelines instances, and makes usage of ``self.outqueue`` to output
+    the data.
 
     A changefeed is a real time feed on inserts, updates, and deletes, and
-    it's volatile. This class is a helper to create changefeeds. Moreover
-    it provides a way to specify a `prefeed`, that is a set of data (iterable)
-    to output before the actual changefeed.
+    is volatile. This class is a helper to create changefeeds. Moreover,
+    it provides a way to specify a ``prefeed`` of iterable data to output
+    before the actual changefeed.
     """
 
     INSERT = 1
@@ -35,8 +35,8 @@ class ChangeFeed(Node):
         Args:
             table (str): name of the table to listen to for changes.
             operation (int): can be ChangeFeed.INSERT, ChangeFeed.DELETE, or
-                ChangeFeed.UPDATE. Combining multiple operation is possible using
-                the bitwise ``|`` operator
+                ChangeFeed.UPDATE. Combining multiple operation is possible
+                with the bitwise ``|`` operator
                 (e.g. ``ChangeFeed.INSERT | ChangeFeed.UPDATE``)
             prefeed (iterable): whatever set of data you want to be published
                 first.

bigchaindb/util.py

@@ -119,7 +119,7 @@ def condition_details_has_owner(condition_details, owner):
 def verify_vote_signature(voters, signed_vote):
     """Verify the signature of a vote
 
-    A valid vote should have been signed `owner_before` corresponding private key.
+    A valid vote should have been signed by a voter's private key.
 
     Args:
         voters (list): voters of the block that is under election