DOCS-141 utility comments

Author: Brandon Diamond

source/reference/bsondump.rst

@@ -42,10 +42,12 @@ Options
 .. option:: --filter '<JSON>'
 
    Limits the documents that :program:`bsondump` exports to only those
-   documents that match the :term:`JSON document` specified as `'<JSON>'`. Be
+   documents that match the :term:`JSON document` specified as ``'<JSON>'``. Be
    sure to include the document in single quotes to avoid a poor
    interaction with your shell.
 
+TODO "poor interaction" may not be appropriate.
+
 .. option:: --type <=json|=debug>
 
    Changes the operation of :program:`bsondump` from outputting ":term:`JSON`" (the
@@ -55,13 +57,17 @@ Options
 
    The final argument to :program:`bsondump` is a bson
 
+TODO above is incomplete sentence. Fix?
+
 Usage
 -----
 
 The output of :program:`bsondump` returns on standard output. To
 create corresponding :term:`JSON` files, you will need to use the
 shell redirect. See the following command:
 
+TODO not sure if "returns on standard output" makes sense. "The output of bsondump defaults to standard output."
+
 .. code-block:: sh
 
    bsondump collection.bson > collection.json

source/reference/mongodump.rst

@@ -67,13 +67,17 @@ Options
    on the standard port. (i.e. ``27017``) You may also specify a port
    number using the :option:`--host <mongodump --host>` command.
 
+TODO is the notation really --host <mongodump --host>, not sure about this
+
 .. option:: --ipv6
 
    Enables :term:`IPv6` support to allow :program:`mongodump` to
    connect to the MongoDB instance using IPv6
    connectivity. All MongoDB programs and processes, including
    :program:`mongodump`, disable IPv6 support by default.
 
+TODO copypaste
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if
@@ -87,6 +91,8 @@ Options
    in conjunction with the :option:`--username <mongodump --username>`
    option to supply a username.
 
+TODO copypaste
+
 .. option:: --dbpath <path>
 
    Specifies the directory of the MongoDB data files. If used, the
@@ -166,6 +172,8 @@ Options
    be an inconsistent state as a result of an improper shutdown or
    :program:`mongod` crash.
 
+TODO use this option *run a repair operation* (some wording errors)
+
 .. option:: --forceTableScan
 
    Forces :program:`mongodump` to scan the data store directly:

source/reference/mongoexport.rst

@@ -66,6 +66,8 @@ Options
    You can always connect directly to a single MongoDB instance by
    specifying the host and port number directly.
 
+TODO copypaste
+
 .. option:: --port <port>
 
    Specifies the port number, if the MongoDB instance is not running on
@@ -79,6 +81,8 @@ Options
    and processes, including :program:`mongoexport`, disable IPv6
    support by default.
 
+TODO copypaste
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if your

source/reference/mongofiles.rst

@@ -46,6 +46,8 @@ Commands
    returned items to files that begin with that string of
    characters.
 
+TODO double space after characters
+
 .. option:: search <string>
 
    Lists the files in the GridFS store with names that match any
@@ -118,6 +120,8 @@ Options
    You can always connect directly to a single MongoDB instance by
    specifying the host and port number directly.
 
+TODO "from which you want to *export* data" doesn't quite make sense in context
+
 .. option:: --port <port>
 
    Specifies the port number, if the MongoDB instance is not running on
@@ -131,6 +135,8 @@ Options
    and processes, including :program:`mongofiles`, disable IPv6 support by
    default.
 
+TODO copypaste
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if your

source/reference/mongoimport.rst

@@ -82,6 +82,8 @@ Options
    and processes, including :program:`mongoimport`, disable IPv6
    support by default.
 
+TODO copypaste
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if your
@@ -94,6 +96,8 @@ Options
    in conjunction with the :option:`mongoimport --username` option to
    supply a username.
 
+TODO copypaste
+
 .. option:: --dbpath <path>
 
    Specifies the directory of the MongoDB data files. If used, the
@@ -117,6 +121,8 @@ Options
 
    Enables journaling for all :program:`mongoimport` operations.
 
+TODO this description seems less detailed than the other --journal descriptions; maybe should describe in more depth.
+
 .. option:: --db <db>, -d <db>
 
    Use the :option:`--db` option to specify a database for
@@ -136,13 +142,17 @@ Options
    restore data into a MongoDB instance that already has data, or to
    restore only some data in the specified imported data set.
 
+TODO this should be mongoimport, not mongorestore
+
 .. option:: --fields <field1[,filed2]>, -f <field1[,filed2]>
 
    Specify a field or number fields to *import* from the data
    export. All other fields present in the export will be *excluded*
    during importation. Comma separate a list of fields to limit the
    fields imported.
 
+TODO "import form the data export" is a little confusing
+
 .. option:: --fieldFile <filename>
 
    As an alternative to ":option:`mongoimport --fields`" the
@@ -261,3 +271,5 @@ instance running on the host ``mongodb1.example.net``" over port
 .. code-block:: sh
 
    mongoexport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --db marketing --file /opt/backups/mdb1-examplenet.json
+
+TODO these are all mongoexport instead of mongoimport

source/reference/mongorestore.rst

@@ -55,6 +55,8 @@ Options
    You can always connect directly to a single MongoDB instance by
    specifying the host and port number directly.
 
+TODO first paragraph, second sentence: "ruining" should be "running"
+
 .. option:: --port <port>
 
    Specifies the port number, if the MongoDB instance is not running
@@ -81,6 +83,8 @@ Options
    in conjunction with the :option:`mongorestore --username` option to
    supply a username.
 
+TODO leave out password to be prompted
+
 .. option:: --dbpath <path>
 
    Specifies the directory of the MongoDB data files. If used, the
@@ -135,6 +139,8 @@ Options
    ``'<JSON>'``. Be sure to include the document in single quotes to
    avoid a poor interaction with your shell.
 
+TODO poor interaction with shell again; not sure how you feel about these
+
 .. option:: --drop
 
    Modifies the restoration procedure to drop every collection from
@@ -172,6 +178,8 @@ In the following command restores the collection named
 on the localhost interface on port ``27017`` the dump located in the
 "``dump/``" directory.
 
+TODO the above is clumsy and hard to follow
+
 .. code-block:: sh
 
    mongorestore --collection collection --database test
@@ -182,6 +190,8 @@ in the ``/srv/mongodb`` on the local machine. This requires there are
 no active :program:`mongod` instances attached to ``/srv/mongodb``
 data directory.
 
+TODO "This requires *that* there are..." - is this better?
+
 .. code-block:: sh
 
    mongorestore --dbpath /srv/mongodb
@@ -192,6 +202,8 @@ running on port "``37017``" on the host "``mongodb1.example.net`` and
 authenticating using the username "``user``" and the password
 "``pass``", as follows:
 
+TODO is "authenticating" the right tense? goodness, my grammar is rusty
+
 .. code-block:: sh
 
    mongorestore --host mongodb1.example.net --port 37017 --username user --password pass /opt/backup/mongodumpm-2011-10-24

source/reference/mongosniff.rst

@@ -17,6 +17,8 @@ MongoDB-specific analogue of ``tcpdump`` for TCP/IP network
 traffic. Typically, :program:`mongosniff` is most frequently used in drier
 development.
 
+TODO s/drier/driver/
+
 .. note::
 
    :program:`mongosniff` requires "libcap" and is only available for

source/reference/mongostat.rst

@@ -37,6 +37,8 @@ on the local host interface on TCP port 27017, but
 :program:`mongostat` can connect to any accessible remote MongoDB
 process.
 
+TODO "but mongostat [can also] ... [as well]"?
+
 Options
 -------
 
@@ -78,6 +80,8 @@ Options
    You can always connect directly to a single MongoDB instance by
    specifying the host and port number directly.
 
+TODO s/ruining/running
+
 .. option:: --port <port>
 
    Specifies the port number, if the MongoDB instance is not running on
@@ -91,6 +95,8 @@ Options
    and processes, including :program:`mongostat`, disable IPv6 support
    by default.
 
+TODO tentative copypaste
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if your
@@ -103,6 +109,8 @@ Options
    in conjunction with the :option:`mongostat --username` option to
    supply a username.
 
+TODO copypaste
+
 .. option:: --noheaders
 
    Disables the output of column or field names.
@@ -322,6 +330,8 @@ group of machines. If a :program:`mongos` process connected to a
 machine, you can use the following form to return statistics from all
 members of the cluster:
 
+TODO "use the --etc will help" - looks like s/use/using/
+
 .. code-block:: sh
 
    mongostat --discover

source/reference/mongotop.rst

@@ -16,6 +16,8 @@ MongoDB instance spends reading and writing data. :program:`mongotop`
 provides statistics on the per-collection level. In default operation,
 :program:`mongotop` returns values every second.
 
+TODO "in default operation" = "by default", maybe less confusing
+
 .. seealso::
 
    For more information about monitoring MongoDB, see
@@ -69,6 +71,8 @@ Options
    of at least one connected set member, connect to primary node of
    that set. this option would resemble:
 
+TODO is "setname" a well-defined mongodb term? I usually write "replica set name" which is pretty clumsy sounding
+
    .. code-block:: sh
 
       --host repl0 mongo0.example.net,mongo0.example.net,27018,mongo1.example.net,mongo2.example.net
@@ -88,6 +92,8 @@ Options
    MongoDB instance using IPv6 connectivity. :program:`mongotop` and
    other MongoDB programs disable IPv6 support by default.
 
+TODO I'm not an ipv6 whiz by any means -- but is "connectivity" the right word? (seems like too much connect* in one sentence)
+
 .. option:: --username <username>, -u <username>
 
    Specifies a username to authenticate to the MongoDB instance, if
@@ -101,6 +107,8 @@ Options
    in conjunction with the :option:`--username <mongotop --username>`
    option to supply a username.
 
+TODO I believe that mongotools will prompt for a password if flag is used without a value
+
 .. option:: <sleeptime>
 
    The final argument the length of time, in seconds, that
@@ -124,6 +132,8 @@ Fields
    shell to generate activity so that an specific namespace appears on
    the page.
 
+TODO ", and includes" should this be ", which includes"?
+
 .. data:: total
 
    Provides the total amount of time that this :program:`mongod` spent