Add warning about localhost,

Author: Ed Costello

source/reference/command/addShard.txt

@@ -6,19 +6,22 @@ addShard
 
 .. dbcommand:: addShard
 
-   :option name: Optional. Unless specified, a name will be
-                 automatically provided to uniquely identify
-                 the shard.
-
-   :option maxSize: Optional. Unless specified, shards will consume
-                    the total amount of available space on their
-                    machines if necessary. Use the ``maxSize`` value
-                    to limit the amount of space the database can
-                    use. Specify this value in megabytes.
-
-   Use this method to add a database instance or replica set to a
-   :term:`sharded cluster`.
+   :param string hostname: a hostname or replica-set/hostname string.
+
+   :param string name: Optional. Unless specified, a name will be
+                       automatically provided to uniquely identify
+                       the shard.
+
+   :param integer maxSize: Optional. Unless specified, shards will consume
+                           the total amount of available space on their
+                           machines if necessary. Use the ``maxSize`` value
+                           to limit the amount of space the database can
+                           use. Specify this value in megabytes.
+
+   Use the :dbcommand:`addShard` command to add a database instance
+   or replica set to a :term:`sharded cluster`.
    You must run this command against a :program:`mongos` instance.
+
    The command takes the following form:
 
    .. code-block:: javascript
@@ -28,13 +31,26 @@ addShard
    Replace ``<hostname>:<port>`` with the hostname and port of the
    database instance you want to add as a shard.
 
-   If the database instance is a member of a replica set, you must specify
-   the replica set name and at least one member of the replica set:
+   .. warning::
+
+      Do not use ``localhost`` for the hostname unless your
+      :term:`configuration server <config database>`
+      is also running on ``localhost``.
+
+   The optimal configuration is to deploy shards across
+   :term:`replica sets <replica set>`.
+   To add a shard on a replica set you must specify the name of the
+   replica set and the hostname of at least one member of the replica
+   set.  You may specify all of the hostnames, but at least one member
+   must be specified.
 
    .. code-block:: javascript
 
       { addShard: "replica-set/hostname:port" }
 
+   If you specify additional hostnames, all must be members of the same
+   replica set.
+
    Send this command to only one :program:`mongos` instance, it will
    store shard configuration information in the :term:`config database`.
 
@@ -48,7 +64,6 @@ addShard
       migrating chunks to the shard when the value of
       :status:`mem.mapped` exceeds the value of ``maxSize``.
 
-
    .. seealso::
 
       :method:`sh.addShard()`,

source/reference/method/sh.addShard.txt

@@ -9,7 +9,6 @@ sh.addShard()
    :param string host: Specify the hostname of a database instance or a
                        replica set configuration.
 
-
    Use this method to add a database instance or replica set to a
    :term:`sharded cluster`.
    This method must be run on a :program:`mongos` instance.
@@ -23,16 +22,26 @@ sh.addShard()
    You can specify shards using the hostname, or a hostname and port
    combination if the shard is running on a non-standard port.
 
+   .. warning::
+
+      Do not use ``localhost`` for the hostname unless your
+      :term:`configuration server <config database>`
+      is also running on ``localhost``.
+
    The optimal configuration is to deploy shards across
    :term:`replica sets <replica set>`.
    To add a shard on a replica set you must specify the name of the
    replica set and the hostname of at least one member of the replica
-   set.  You can specify all of the hostnames, but at least one member
+   set.  You may specify all of the hostnames, but at least one member
    must be specified.
 
-   This method is a helper for the :dbcommand:`addShard` command.
+   If you specify additional hostnames, all must be members of the same
+   replica set.
+
+   The :method:`~sh.addShard()` method is a helper for the
+   :dbcommand:`addShard` command.
    The :dbcommand:`addShard` command has additional options which are
-   not available in this method.
+   not available with this helper.
 
    .. seealso::
 

source/tutorial/add-shards-to-shard-cluster.txt

@@ -48,6 +48,12 @@ Or you can use the :method:`sh.addShard()` helper in the
 Replace ``[hostname]`` and ``[port]`` with the hostname and TCP
 port number of where the shard is accessible.
 
+.. warning::
+
+   Do not use ``localhost`` for the hostname unless your
+   :term:`configuration server <config database>`
+   is also running on ``localhost``.
+
 For example:
 
 .. code-block:: javascript