Tinker with dockstrings in back-ends and related places

Change-Id: If80509e2e19cec5d0b8c5cfccd15e6d893558de4

swift/account/backend.py

@@ -31,14 +31,14 @@ from swift.common.db import DatabaseBroker, DatabaseConnectionError, \
 
 
 class AccountBroker(DatabaseBroker):
-    """Encapsulates working with a account database."""
+    """Encapsulates working with an account database."""
     db_type = 'account'
     db_contains_type = 'container'
     db_reclaim_timestamp = 'delete_timestamp'
 
     def _initialize(self, conn, put_timestamp):
         """
-        Create a brand new database (tables, indices, triggers, etc.)
+        Create a brand new account database (tables, indices, triggers, etc.)
 
         :param conn: DB connection object
         :param put_timestamp: put timestamp
@@ -103,6 +103,7 @@ class AccountBroker(DatabaseBroker):
     def create_account_stat_table(self, conn, put_timestamp):
         """
         Create account_stat table which is specific to the account DB.
+        Not a part of Pluggable Back-ends, internal to the baseline code.
 
         :param conn: DB connection object
         :param put_timestamp: put timestamp
@@ -156,6 +157,7 @@ class AccountBroker(DatabaseBroker):
             WHERE delete_timestamp < ? """, (timestamp, timestamp, timestamp))
 
     def _commit_puts_load(self, item_list, entry):
+        """See :func:`swift.common.db.DatabaseBroker._commit_puts_load`"""
         (name, put_timestamp, delete_timestamp,
          object_count, bytes_used, deleted) = \
             pickle.loads(entry.decode('base64'))

swift/common/db.py

@@ -536,7 +536,7 @@ class DatabaseBroker(object):
         """
         Unmarshall the :param:entry and append it to :param:item_list.
         This is implemented by a particular broker to be compatible
-        with its merge_items().
+        with its :func:`merge_items`.
         """
         raise NotImplementedError
 
@@ -622,7 +622,7 @@ class DatabaseBroker(object):
         that key was set to that value. Key/values will only be overwritten if
         the timestamp is newer. To delete a key, set its value to ('',
         timestamp). These empty keys will eventually be removed by
-        :func:reclaim
+        :func:`reclaim`
         """
         old_metadata = self.metadata
         if set(metadata_updates).issubset(set(old_metadata)):
@@ -659,7 +659,7 @@ class DatabaseBroker(object):
         from incoming_sync and outgoing_sync where the updated_at timestamp is
         < sync_timestamp.
 
-        In addition, this calls the DatabaseBroker's :func:_reclaim method.
+        In addition, this calls the DatabaseBroker's :func:`_reclaim` method.
 
         :param age_timestamp: max created_at timestamp of object rows to delete
         :param sync_timestamp: max update_at timestamp of sync rows to delete

swift/container/backend.py

@@ -37,7 +37,9 @@ class ContainerBroker(DatabaseBroker):
     db_reclaim_timestamp = 'created_at'
 
     def _initialize(self, conn, put_timestamp):
-        """Creates a brand new database (tables, indices, triggers, etc.)"""
+        """
+        Create a brand new container database (tables, indices, triggers, etc.)
+        """
         if not self.account:
             raise ValueError(
                 'Attempting to create a new database with no account set')
@@ -50,6 +52,7 @@ class ContainerBroker(DatabaseBroker):
     def create_object_table(self, conn):
         """
         Create the object table which is specifc to the container DB.
+        Not a part of Pluggable Back-ends, internal to the baseline code.
 
         :param conn: DB connection object
         """
@@ -91,6 +94,7 @@ class ContainerBroker(DatabaseBroker):
     def create_container_stat_table(self, conn, put_timestamp=None):
         """
         Create the container_stat table which is specific to the container DB.
+        Not a part of Pluggable Back-ends, internal to the baseline code.
 
         :param conn: DB connection object
         :param put_timestamp: put timestamp
@@ -159,6 +163,7 @@ class ContainerBroker(DatabaseBroker):
             WHERE delete_timestamp < ? """, (timestamp, timestamp, timestamp))
 
     def _commit_puts_load(self, item_list, entry):
+        """See :func:`swift.common.db.DatabaseBroker._commit_puts_load`"""
         (name, timestamp, size, content_type, etag, deleted) = \
             pickle.loads(entry.decode('base64'))
         item_list.append({'name': name,
@@ -170,7 +175,7 @@ class ContainerBroker(DatabaseBroker):
 
     def empty(self):
         """
-        Check if the DB is empty.
+        Check if container DB is empty.
 
         :returns: True if the database has no active objects, False otherwise
         """
@@ -334,7 +339,7 @@ class ContainerBroker(DatabaseBroker):
     def reported(self, put_timestamp, delete_timestamp, object_count,
                  bytes_used):
         """
-        Update reported stats.
+        Update reported stats, available with container's `get_info`.
 
         :param put_timestamp: put_timestamp to update
         :param delete_timestamp: delete_timestamp to update

swift/obj/server.py

@@ -217,6 +217,7 @@ class ObjectController(object):
         Update the expiring objects container when objects are updated.
 
         :param op: operation performed (ex: 'PUT', or 'DELETE')
+        :param delete_at: scheduled delete in UNIX seconds, int
         :param account: account name for the object
         :param container: container name for the object
         :param obj: object name