From 0462726907283d5aea6e71428e6acdf40682f1ef Mon Sep 17 00:00:00 2001
From: Mike Dirolf <mike@10gen.com>
Date: Tue, 27 Jan 2009 11:01:26 -0500
Subject: [PATCH] documentation: use epydoc format for rST parameter lists

---
 gridfs/__init__.py         | 14 ++++-----
 gridfs/grid_file.py        | 24 ++++++++-------
 pymongo/bson.py            | 12 ++++----
 pymongo/collection.py      | 63 +++++++++++++++++++-------------------
 pymongo/connection.py      | 42 +++++++++++++------------
 pymongo/cursor.py          | 18 +++++------
 pymongo/cursor_manager.py  | 16 +++++-----
 pymongo/database.py        | 62 +++++++++++++++++++------------------
 pymongo/dbref.py           |  6 ++--
 pymongo/mongo.py           | 31 ++++++++++---------
 pymongo/objectid.py        |  8 ++---
 pymongo/son_manipulator.py | 16 +++++-----
 12 files changed, 161 insertions(+), 151 deletions(-)

diff --git a/gridfs/__init__.py b/gridfs/__init__.py
index 53c75bd83..764604601 100644
--- a/gridfs/__init__.py
+++ b/gridfs/__init__.py
@@ -32,8 +32,8 @@ class GridFS(object):
         Raises TypeError if database is not an instance of
         `pymongo.database.Database`.
 
-        Arguments:
-        - `database`: database to use
+        :Parameters:
+          - `database`: database to use
         """
         if not isinstance(database, Database):
             raise TypeError("database must be an instance of Database")
@@ -46,9 +46,9 @@ class GridFS(object):
         Shorthand method for creating / opening a GridFile from a filename. mode
         must be a mode supported by `gridfs.grid_file.GridFile`
 
-        Arguments:
-        - `filename`: the name of the GridFile to open
-        - `mode` (optional): the mode to open the file in
+        :Parameters:
+          - `filename`: the name of the GridFile to open
+          - `mode` (optional): the mode to open the file in
         """
         return GridFile({"filename": filename}, self.__database, mode)
 
@@ -60,8 +60,8 @@ class GridFS(object):
         all GridFiles that match filename_or_spec. Raises TypeError if
         filename_or_spec is not an instance of (str, unicode, dict, SON).
 
-        Arguments:
-        - `filename_or_spec`: identifier of file(s) to remove
+        :Parameters:
+          - `filename_or_spec`: identifier of file(s) to remove
         """
         spec = filename_or_spec
         if isinstance(filename_or_spec, types.StringTypes):
diff --git a/gridfs/grid_file.py b/gridfs/grid_file.py
index 2d554aafd..18a9f6fb1 100644
--- a/gridfs/grid_file.py
+++ b/gridfs/grid_file.py
@@ -58,11 +58,13 @@ class GridFile(object):
           * only used for querying, automatically set for inserts
         - "aliases": array of alias strings
 
-        Arguments:
-        - `file_spec`: query specifier as described above
-        - `database`: the database to store/retrieve this file in
-        - `mode` (optional): the mode to open this file with, one of ("r", "w")
-        - `collection` (optional): the collection to store/retrieve this file in
+        :Parameters:
+          - `file_spec`: query specifier as described above
+          - `database`: the database to store/retrieve this file in
+          - `mode` (optional): the mode to open this file with, one of
+            ("r", "w")
+          - `collection` (optional): the collection in which to store/retrieve
+            this file
         """
         if not isinstance(file_spec, (types.DictType, SON)):
             raise TypeError("file_spec must be an instance of (dict, SON)")
@@ -156,8 +158,8 @@ class GridFile(object):
         Due to buffering, the rename might not actually occur until `flush()` or
         `close()` is called.
 
-        Arguments:
-        - `filename`: the new name for this GridFile
+        :Parameters:
+          - `filename`: the new name for this GridFile
         """
         file = self.__collection.find_one(self.__id)
         file["filename"] = filename
@@ -207,8 +209,8 @@ class GridFile(object):
         The bytes are returned as a string object. If size is negative or omitted
         all data is read. Raises ValueError if this GridFile is already closed.
 
-        Arguments:
-        - `size` (optional): the number of bytes to read
+        :Parameters:
+          - `size` (optional): the number of bytes to read
         """
         self.__assert_open("r")
 
@@ -251,8 +253,8 @@ class GridFile(object):
         this GridFile is already closed. Raises TypeErrer if str is not an
         instance of str.
 
-        Arguments:
-        - `str`: string of bytes to be written to the file
+        :Parameters:
+          - `str`: string of bytes to be written to the file
         """
         self.__assert_open("w")
 
diff --git a/pymongo/bson.py b/pymongo/bson.py
index a9d3ef7e0..b7d90bc2b 100644
--- a/pymongo/bson.py
+++ b/pymongo/bson.py
@@ -408,8 +408,8 @@ def is_valid(bson):
     Raises TypeError if the data is not an instance of a subclass of str.
     Returns True if the data represents a valid BSON object, False otherwise.
 
-    Arguments:
-    - `bson`: the data to be validated
+    :Parameters:
+      - `bson`: the data to be validated
     """
     if not isinstance(bson, types.StringType):
         raise TypeError("BSON data must be an instance of a subclass of str")
@@ -442,8 +442,8 @@ class BSON(str):
         The data given must be a string instance and represent a valid BSON
         object, otherwise an TypeError or InvalidBSON exception is raised.
 
-        Arguments:
-        - `bson`: the initial data
+        :Parameters:
+          - `bson`: the initial data
         """
         if not is_valid(bson):
             raise InvalidBSON()
@@ -458,8 +458,8 @@ class BSON(str):
         that are not instance of (str, unicode). Raises InvalidDocument if the
         dictionary cannot be converted to BSON.
 
-        Arguments:
-        - `dict`: mapping type representing a Mongo document
+        :Parameters:
+          - `dict`: mapping type representing a Mongo document
         """
         try:
             elements = "".join([_element_to_bson(key, value) for (key, value) in dict.iteritems()])
diff --git a/pymongo/collection.py b/pymongo/collection.py
index 900f7e06b..7a3fe9263 100644
--- a/pymongo/collection.py
+++ b/pymongo/collection.py
@@ -37,10 +37,10 @@ class Collection(object):
         command will be sent to the database. Otherwise the collection will be
         created implicitly on first use.
 
-        Arguments:
-        - `database`: the database to get a collection from
-        - `name`: the name of the collection to get
-        - `options`: dictionary of collection options.
+        :Parameters:
+          - `database`: the database to get a collection from
+          - `name`: the name of the collection to get
+          - `options`: dictionary of collection options.
             see `pymongo.database.Database.create_collection` for details.
         """
         if not isinstance(name, types.StringTypes):
@@ -77,8 +77,8 @@ class Collection(object):
 
         Raises InvalidName if an invalid collection name is used.
 
-        Arguments:
-        - `name`: the name of the collection to get
+        :Parameters:
+          - `name`: the name of the collection to get
         """
         return Collection(self.__database, u"%s.%s" % (self.__collection_name, name))
 
@@ -117,9 +117,9 @@ class Collection(object):
 
         Raises TypeError if to_save is not an instance of (dict, SON).
 
-        Arguments:
-        - `to_save`: the SON object to be saved
-        - `manipulate` (optional): manipulate the son object before saving it
+        :Parameters:
+          - `to_save`: the SON object to be saved
+          - `manipulate` (optional): manipulate the son object before saving it
         """
         if not isinstance(to_save, (types.DictType, SON)):
             raise TypeError("cannot save object of type %s" % type(to_save))
@@ -138,9 +138,9 @@ class Collection(object):
         SONManipulators that have been added to this database. Returns the
         inserted object or a list of inserted objects.
 
-        Arguments:
-        - `doc_or_docs`: a SON object or list of SON objects to be inserted
-        - `manipulate` (optional): monipulate the objects before inserting?
+        :Parameters:
+          - `doc_or_docs`: a SON object or list of SON objects to be inserted
+          - `manipulate` (optional): monipulate the objects before inserting?
         """
         docs = doc_or_docs
         if isinstance(docs, (types.DictType, SON)):
@@ -163,13 +163,14 @@ class Collection(object):
         Raises TypeError if either spec or document isn't an instance of
         (dict, SON) or upsert isn't an instance of bool.
 
-        - `spec`: a SON object specifying elements which must be present for a
+        :Parameters:
+          - `spec`: a SON object specifying elements which must be present for a
             document to be updated
-        - `document`: a SON object specifying the fields to be changed in the
+          - `document`: a SON object specifying the fields to be changed in the
             selected document(s), or (in the case of an upsert) the document to
             be inserted.
-        - `upsert` (optional): perform an upsert operation
-        - `manipulate` (optional): monipulate the document before updating?
+          - `upsert` (optional): perform an upsert operation
+          - `manipulate` (optional): monipulate the document before updating?
         """
         if not isinstance(spec, (types.DictType, SON)):
             raise TypeError("spec must be an instance of (dict, SON)")
@@ -193,8 +194,8 @@ class Collection(object):
         Raises TypeEror if the argument is not an instance of
         (dict, SON, ObjectId).
 
-        Arguments:
-        - `spec_or_object_id` (optional): a SON object specifying elements
+        :Parameters:
+          - `spec_or_object_id` (optional): a SON object specifying elements
             which must be present for a document to be removed OR an instance of
             ObjectId to be used as the value for an _id element
         """
@@ -213,8 +214,8 @@ class Collection(object):
         Raises TypeError if the argument is of an improper type. Returns a
         single SON object, or None if no result is found.
 
-        Arguments:
-        - `spec_or_object_id` (optional): a SON object specifying elements
+        :Parameters:
+          - `spec_or_object_id` (optional): a SON object specifying elements
             which must be present for a document to be included in the result
             set OR an instance of ObjectId to be used as the value for an _id
             query
@@ -233,14 +234,14 @@ class Collection(object):
         Raises TypeError if any of the arguments are of improper type. Returns
         an instance of Cursor corresponding to this query.
 
-        Arguments:
-        - `spec` (optional): a SON object specifying elements which must be
+        :Parameters:
+          - `spec` (optional): a SON object specifying elements which must be
             present for a document to be included in the result set
-        - `fields` (optional): a list of field names that should be returned
+          - `fields` (optional): a list of field names that should be returned
             in the result set
-        - `skip` (optional): the number of documents to omit (from the start of
-            the result set) when returning the results
-        - `limit` (optional): the maximum number of results to return in the
+          - `skip` (optional): the number of documents to omit (from the start
+            of the result set) when returning the results
+          - `limit` (optional): the maximum number of results to return in the
             first reply message, or 0 for the default return size
         """
         if not isinstance(spec, (types.DictType, SON)):
@@ -273,10 +274,10 @@ class Collection(object):
         direction(s) must be one of (Mongo.ASCENDING, Mongo.DESCENDING). Returns
         the name of the created index.
 
-        Arguments:
-        - `key_or_list`: a single key or a list of (key, direction) pairs
+        :Parameters:
+          - `key_or_list`: a single key or a list of (key, direction) pairs
             specifying the index to ensure
-        - `direction` (optional): must be included if key_or_list is a single
+          - `direction` (optional): must be included if key_or_list is a single
             key, otherwise must be None
         """
         if direction:
@@ -320,8 +321,8 @@ class Collection(object):
         Raises OperationFailure on an error. Raises TypeError if index is not an
         instance of (str, unicode).
 
-        Arguments:
-        - `index`: the name of the index to drop
+        :Parameters:
+          - `index`: the name of the index to drop
         """
         if not isinstance(index, types.StringTypes):
             raise TypeError("index must be an instance of (str, unicode)")
diff --git a/pymongo/connection.py b/pymongo/connection.py
index c7516e90e..4b85eb928 100644
--- a/pymongo/connection.py
+++ b/pymongo/connection.py
@@ -33,10 +33,10 @@ class Connection(object):
         instance of int. Raises ConnectionFailure if the connection cannot be
         made.
 
-        Arguments:
-        - `host` (optional): the hostname or IPv4 address of the database to
+        :Parameters:
+          - `host` (optional): the hostname or IPv4 address of the database to
             connect to
-        - `port` (optional): the port number on which to connect
+          - `port` (optional): the port number on which to connect
         """
         if not isinstance(host, types.StringType):
             raise TypeError("host must be an instance of str")
@@ -56,6 +56,9 @@ class Connection(object):
         cursor manager handles closing cursors. Different managers can implement
         different policies in terms of when to actually kill a cursor that has
         been closed.
+
+        :Parameters:
+          - `manager_class`: cursor manager to use
         """
         manager = manager_class(self)
         if not isinstance(manager, CursorManager):
@@ -89,9 +92,9 @@ class Connection(object):
         Raises ConnectionFailure if the message cannot be sent. Returns the
         request id of the sent message.
 
-        Arguments:
-        - `operation`: the opcode of the message
-        - `data`: the data to send
+        :Parameters:
+          - `operation`: the opcode of the message
+          - `data`: the data to send
         """
         # header
         to_send = struct.pack("<i", 16 + len(data))
@@ -118,9 +121,10 @@ class Connection(object):
         and request id. Calls to receive_message and send_message should be done
         synchronously.
 
-        Arguments:
-        - `operation`: the opcode of the message
-        - `request_id`: the request id that the message should be in response to
+        :Parameters:
+          - `operation`: the opcode of the message
+          - `request_id`: the request id that the message should be in response
+            to
         """
         def receive(length):
             message = ""
@@ -151,8 +155,8 @@ class Connection(object):
 
         Raises InvalidName if an invalid database name is used.
 
-        Arguments:
-        - `name`: the name of the database to get
+        :Parameters:
+          - `name`: the name of the database to get
         """
         return Database(self, name)
 
@@ -161,8 +165,8 @@ class Connection(object):
 
         Raises InvalidName if an invalid database name is used.
 
-        Arguments:
-        - `name`: the name of the database to get
+        :Parameters:
+          - `name`: the name of the database to get
         """
         return self.__getattr__(name)
 
@@ -173,8 +177,8 @@ class Connection(object):
         closing the cursor actually means depends on this connection's cursor
         manager.
 
-        Arguments:
-        - `cursor_id`: cursor id to close
+        :Parameters:
+          - `cursor_id`: cursor id to close
         """
         if not isinstance(cursor_id, (types.IntType, types.LongType)):
             raise TypeError("cursor_id must be an instance of (int, long)")
@@ -186,8 +190,8 @@ class Connection(object):
 
         Raises TypeError if cursor_ids is not an instance of list.
 
-        Arguments:
-        - `cursor_ids`: list of cursor ids to kill
+        :Parameters:
+          - `cursor_ids`: list of cursor ids to kill
         """
         if not isinstance(cursor_ids, types.ListType):
             raise TypeError("cursor_ids must be a list")
@@ -214,8 +218,8 @@ class Connection(object):
     def drop_database(self, name_or_database):
         """Drop a database.
 
-        Arguments:
-        - `name_or_database`: the name of a database to drop or the object
+        :Parameters:
+          - `name_or_database`: the name of a database to drop or the object
             itself
         """
         name = name_or_database
diff --git a/pymongo/cursor.py b/pymongo/cursor.py
index 534fb259e..5617ec19f 100644
--- a/pymongo/cursor.py
+++ b/pymongo/cursor.py
@@ -95,8 +95,8 @@ class Cursor(object):
         Raises TypeError if limit is not an instance of int. Raises
         InvalidOperation if this cursor has already been used.
 
-        Arguments:
-        - `limit`: the number of results to return
+        :Parameters:
+          - `limit`: the number of results to return
         """
         if not isinstance(limit, types.IntType):
             raise TypeError("limit must be an int")
@@ -111,8 +111,8 @@ class Cursor(object):
         Raises TypeError if skip is not an instance of int. Raises
         InvalidOperation if this cursor has already been used.
 
-        Arguments:
-        - `skip`: the number of results to skip
+        :Parameters:
+          - `skip`: the number of results to skip
         """
         if not isinstance(skip, types.IntType):
             raise TypeError("skip must be an int")
@@ -129,10 +129,10 @@ class Cursor(object):
         direction(s) must be one of (Mongo.ASCENDING, Mongo.DESCENDING). Raises
         InvalidOperation if this cursor has already been used.
 
-        Arguments:
-        - `key_or_list`: a single key or a list of (key, direction) pairs
+        :Parameters:
+          - `key_or_list`: a single key or a list of (key, direction) pairs
             specifying the keys to sort on
-        - `direction` (optional): must be included if key_or_list is a single
+          - `direction` (optional): must be included if key_or_list is a single
             key, otherwise must be None
         """
         self.__check_okay_to_chain()
@@ -198,8 +198,8 @@ class Cursor(object):
         create_index) or an index (as passed to create_index). If index_or_name
         is None any existing hints for this query are cleared.
 
-        Arguments:
-        - `index_or_name`: index (or name of the index) to hint on
+        :Parameters:
+          - `index_or_name`: index (or name of the index) to hint on
         """
         self.__check_okay_to_chain()
         if index_or_name is None:
diff --git a/pymongo/cursor_manager.py b/pymongo/cursor_manager.py
index 0853611ed..fb505aadc 100644
--- a/pymongo/cursor_manager.py
+++ b/pymongo/cursor_manager.py
@@ -27,8 +27,8 @@ class CursorManager(object):
     def __init__(self, connection):
         """Instantiate the manager.
 
-        Arguments:
-        - `connection`: a Mongo Connection
+        :Parameters:
+          - `connection`: a Mongo Connection
         """
         self.__connection = connection
 
@@ -37,8 +37,8 @@ class CursorManager(object):
 
         Raises TypeError if cursor_id is not an instance of (int, long).
 
-        Arguments:
-        - `cursor_id`: cursor id to close
+        :Parameters:
+          - `cursor_id`: cursor id to close
         """
         if not isinstance(cursor_id, (types.IntType, types.LongType)):
             raise TypeError("cursor_id must be an instance of (int, long)")
@@ -51,8 +51,8 @@ class BatchCursorManager(CursorManager):
     def __init__(self, connection):
         """Instantiate the manager.
 
-        Arguments:
-        - `connection`: a Mongo Connection
+        :Parameters:
+          - `connection`: a Mongo Connection
         """
         self.__dying_cursors = []
         self.__max_dying_cursors = 20
@@ -70,8 +70,8 @@ class BatchCursorManager(CursorManager):
 
         Raises TypeError if cursor_id is not an instance of (int, long).
 
-        Arguments:
-        - `cursor_id`: cursor id to close
+        :Parameters:
+          - `cursor_id`: cursor id to close
         """
         if not isinstance(cursor_id, (types.IntType, types.LongType)):
             raise TypeError("cursor_id must be an instance of (int, long)")
diff --git a/pymongo/database.py b/pymongo/database.py
index 271121a15..4f77b796e 100644
--- a/pymongo/database.py
+++ b/pymongo/database.py
@@ -41,9 +41,9 @@ class Database(object):
         Raises TypeError if name is not an instance of (str, unicode). Raises
         InvalidName if name is not a valid database name.
 
-        Arguments:
-        - `connection`: a connection to Mongo
-        - `name`: database name
+        :Parameters:
+          - `connection`: a connection to Mongo
+          - `name`: database name
         """
         if not isinstance(name, types.StringTypes):
             raise TypeError("name must be an instance of (str, unicode)")
@@ -64,9 +64,10 @@ class Database(object):
     def add_son_manipulator(self, manipulator, index=-1):
         """Add a new son manipulator to this database.
 
-        Arguments:
-        - `manipulator`: the manipulator to add
-        - `index` (optional): the index to add the manipulator on the manipulator list
+        :Parameters:
+          - `manipulator`: the manipulator to add
+          - `index` (optional): the index to add the manipulator on the
+            manipulator list
         """
         self.__manipulators[index:index] = [manipulator]
 
@@ -93,8 +94,8 @@ class Database(object):
 
         Raises InvalidName if an invalid collection name is used.
 
-        Arguments:
-        - `name`: the name of the collection to get
+        :Parameters:
+          - `name`: the name of the collection to get
         """
         return Collection(self, name)
 
@@ -103,8 +104,8 @@ class Database(object):
 
         Raises InvalidName if an invalid collection name is used.
 
-        Arguments:
-        - `name`: the name of the collection to get
+        :Parameters:
+          - `name`: the name of the collection to get
         """
         return self.__getattr__(name)
 
@@ -116,15 +117,16 @@ class Database(object):
         collection already exists.
 
         Options should be a dictionary, with any of the following options:
+
         - "size": desired initial size for the collection. must be less than or
-            equal to 10000000000. for capped collections this size is the max
-            size of the collection.
+          equal to 10000000000. for capped collections this size is the max
+          size of the collection.
         - "capped": if True, this is a capped collection
         - "max": maximum number of objects if capped (optional)
 
-        Arguments:
-        - `name`: the name of the collection to create
-        - `options` (optional): options to use on the new collection
+        :Parameters:
+          - `name`: the name of the collection to create
+          - `options` (optional): options to use on the new collection
         """
         if name in self.collection_names():
             raise CollectionInvalid("collection %s already exists" % name)
@@ -134,9 +136,9 @@ class Database(object):
     def _fix_incoming(self, son, collection):
         """Apply manipulators to an incoming SON object before it gets stored.
 
-        Arguments:
-        - `son`: the son object going into the database
-        - `collection`: the collection the son object is being saved in
+        :Parameters:
+          - `son`: the son object going into the database
+          - `collection`: the collection the son object is being saved in
         """
         for manipulator in self.__manipulators:
             son = manipulator.transform_incoming(son, collection)
@@ -145,9 +147,9 @@ class Database(object):
     def _fix_outgoing(self, son, collection):
         """Apply manipulators to a SON object as it comes out of the database.
 
-        Arguments:
-        - `son`: the son object coming out of the database
-        - `collection`: the collection the son object was saved in
+        :Parameters:
+          - `son`: the son object coming out of the database
+          - `collection`: the collection the son object was saved in
         """
         for manipulator in self.__manipulators:
             son = manipulator.transform_outgoing(son, collection)
@@ -171,8 +173,8 @@ class Database(object):
     def drop_collection(self, name_or_collection):
         """Drop a collection.
 
-        Arguments:
-        - `name_or_collection`: the name of a collection to drop or the
+        :Parameters:
+          - `name_or_collection`: the name of a collection to drop or the
             collection object itself
         """
         name = name_or_collection
@@ -230,8 +232,8 @@ class Database(object):
 
         Raises ValueError if level is not one of (OFF, SLOW_ONLY, ALL).
 
-        Arguments:
-        - `level`: the profiling level to use
+        :Parameters:
+          - `level`: the profiling level to use
         """
         if not isinstance(level, types.IntType) or level < 0 or level > 2:
             raise ValueError("level must be one of (OFF, SLOW_ONLY, ALL)")
@@ -303,9 +305,9 @@ class Database(object):
         to *all* databases. Effectively, "admin" access means root access to the
         database.
 
-        Arguments:
-        - `name`: the name of the user to authenticate
-        - `password`: the password of the user to authenticate
+        :Parameters:
+          - `name`: the name of the user to authenticate
+          - `password`: the password of the user to authenticate
         """
         if not isinstance(name, types.StringTypes):
             raise TypeError("name must be an instance of (str, unicode)")
@@ -341,8 +343,8 @@ class Database(object):
         Raises TypeError if dbref is not an instance of DBRef. Returns a SON
         object or None if the reference does not point to a valid object.
 
-        Arguments:
-        - `dbref`: the reference
+        :Parameters:
+          - `dbref`: the reference
         """
         if not isinstance(dbref, DBRef):
             raise TypeError("cannot dereference a %s" % type(dbref))
diff --git a/pymongo/dbref.py b/pymongo/dbref.py
index 709361142..6e7a8382d 100644
--- a/pymongo/dbref.py
+++ b/pymongo/dbref.py
@@ -27,9 +27,9 @@ class DBRef(object):
         Raises TypeError if collection is not an instance of (str, unicode) or
         id is not an instance of ObjectId.
 
-        Arguments:
-        - `collection`: the collection the object is stored in
-        - `id`: the value of the object's _id field
+        :Parameters:
+          - `collection`: the collection the object is stored in
+          - `id`: the value of the object's _id field
         """
         if not isinstance(collection, types.StringTypes):
             raise TypeError("collection must be an instance of (str, unicode)")
diff --git a/pymongo/mongo.py b/pymongo/mongo.py
index fb00ec95f..229721d2d 100644
--- a/pymongo/mongo.py
+++ b/pymongo/mongo.py
@@ -44,17 +44,18 @@ class Mongo(database.Database):
 
         Settings are passed in as a dictionary. Possible settings, along with
         their default values (in parens), are listed below:
-        - "auto_dereference" (False): automatically dereference any `DBRef`s
-            contained within SON objects being returned from queries
-        - "auto_reference" (False): automatically create `DBRef`s out of any
-            sub-objects that have already been saved in the database
 
-        Arguments:
-        - `name`: the name of the database to connect to
-        - `host` (optional): the hostname or IPv4 address of the database to
+        - "auto_dereference" (False): automatically dereference any `DBRef`
+          contained within SON objects being returned from queries
+        - "auto_reference" (False): automatically create `DBRef` out of any
+          sub-objects that have already been saved in the database
+
+        :Parameters:
+          - `name`: the name of the database to connect to
+          - `host` (optional): the hostname or IPv4 address of the database to
             connect to
-        - `port` (optional): the port number on which to connect
-        - `settings` (optional): a dictionary of settings
+          - `port` (optional): the port number on which to connect
+          - `settings` (optional): a dictionary of settings
         """
         if not isinstance(settings, types.DictType):
             raise TypeError("settings must be an instance of dict")
@@ -79,9 +80,9 @@ class Mongo(database.Database):
 
         Used to do things like auto dereferencing, if the option is enabled.
 
-        Arguments:
-        - `son`: a SON object coming out of the database
-        - `collection`: collection this object is being retrieved from
+        :Parameters:
+          - `son`: a SON object coming out of the database
+          - `collection`: collection this object is being retrieved from
         """
         son = database.Database._fix_outgoing(self, son, collection)
 
@@ -112,9 +113,9 @@ class Mongo(database.Database):
         Will also add _id and _ns if they are missing and desired (as specified
         by add_meta).
 
-        Arguments:
-        - `to_save`: a SON object going into the database
-        - `collection`: collection into which this object is being saved
+        :Parameters:
+          - `to_save`: a SON object going into the database
+          - `collection`: collection into which this object is being saved
         """
         to_save = database.Database._fix_incoming(self, to_save, collection)
 
diff --git a/pymongo/objectid.py b/pymongo/objectid.py
index 151f5439f..cad610390 100644
--- a/pymongo/objectid.py
+++ b/pymongo/objectid.py
@@ -29,8 +29,8 @@ class ObjectId(object):
         Otherwise, a TypeError is raised. If given an invalid id, InvalidId is
         raised.
 
-        Arguments:
-        - `id` (optional): a valid ObjectId
+        :Parameters:
+          - `id` (optional): a valid ObjectId
         """
         if id is None:
             self.__generate()
@@ -53,8 +53,8 @@ class ObjectId(object):
         Raises TypeError if id is not an instance of (str, ObjectId) and
         InvalidId if it is not a valid ObjectId.
 
-        Arguments:
-        - `id`: a valid ObjectId
+        :Parameters:
+          - `oid`: a valid ObjectId
         """
         if isinstance(oid, ObjectId):
             self.__id = oid.__id
diff --git a/pymongo/son_manipulator.py b/pymongo/son_manipulator.py
index 0489c61f0..1ec2774f3 100644
--- a/pymongo/son_manipulator.py
+++ b/pymongo/son_manipulator.py
@@ -28,26 +28,26 @@ class SONManipulator(object):
     def __init__(self, database):
         """Instantiate the manager.
 
-        Arguments:
-        - `database`: a Mongo Database
+        :Parameters:
+          - `database`: a Mongo Database
         """
         self.__database = database
 
     def transform_incoming(self, son, collection):
         """Manipulate an incoming son object.
 
-        Arguments:
-        - `son`: the son object to be inserted into the database
-        - `collection`: the collection the object is being inserted into
+        :Parameters:
+          - `son`: the son object to be inserted into the database
+          - `collection`: the collection the object is being inserted into
         """
         return son
 
     def transform_outgoing(self, son, collection):
         """Manipulate an outgoing son object.
 
-        Arguments:
-        - `son`: the son object being retrieved from the database
-        - `collection`: the collection this object was stored in
+        :Parameters:
+          - `son`: the son object being retrieved from the database
+          - `collection`: the collection this object was stored in
         """
         return son