DOCSP-20098 updates isBalancerRunning method output (#162)

* DOCSP-20098 updates isBalancerRunning method output

* adds reference links for ok, clusterTime, and operationTime

* adds links to new refs

* updates ref links in source/includes/fact-runCommand-results.rst

* updates sh.isBalancerRunning() description across reference pages

* fixes spacing issue

* provide more specific ref paths to prevent "Ambiguous target" errors

* ref links

* removes single quotes

* each item desc references the section, rather than the individual fields

* rephrases operationTime definition

* cleans up include

* removes extra whitespace

Author: jmd-mongo

source/includes/fact-runCommand-results.rst

@@ -11,14 +11,14 @@
 
    * - ``ok``
 
-     - A number that indicates whether the command has succeeded
-       (``1``) or failed (``0``).
+     - A number that indicates whether the command has succeeded (``1``)
+       or failed (``0``).
 
    * - ``operationTime``
 
-     - The logical time of the performed operation, represented in
-       MongoDB by the timestamp from the oplog entry. *Only for replica
-       sets and sharded clusters*
+     - The logical time of the operation. MongoDB uses the logical time 
+       to order operations. *Only for replica sets and sharded 
+       clusters.*
 
        If the command does not generate an oplog entry, e.g. a read
        operation, then the operation does not advance the logical

source/reference/method.txt

@@ -998,7 +998,7 @@ Sharding
 
    * - :method:`sh.isBalancerRunning()`
 
-     - Returns a boolean to report if the balancer process is currently migrating chunks.
+     - Returns a document describing the status of the balancer.
 
    * - :method:`sh.moveChunk()`
 

source/reference/method/js-sharding.txt

@@ -98,7 +98,7 @@ Sharding Methods
 
    * - :method:`sh.isBalancerRunning()`
 
-     - Returns a boolean to report if the balancer process is currently migrating chunks.
+     - Returns a document describing the status of the balancer.
 
    * - :method:`sh.moveChunk()`
 

source/reference/method/sh.isBalancerRunning.txt

@@ -10,14 +10,78 @@ sh.isBalancerRunning()
    :depth: 1
    :class: singlecol
 
+Definition
+----------
+
 .. method:: sh.isBalancerRunning()
 
-   :returns: boolean
+   Returns a document describing the status of the balancer.
+
+Output Document
+---------------
+
+The following is an example of a document returned by the command:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+     mode: 'full',
+     inBalancerRound: false,
+     numBalancerRounds: Long("1143"),
+     ok: 1,
+     '$clusterTime': {
+        clusterTime: Timestamp({ t: 1639753724, i: 3 }),
+        signature: {
+           hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
+           keyId: Long("0")
+        }
+     },
+     operationTime: Timestamp({ t: 1639753724, i: 3 })
+   }
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Field
+     - Description
+
+   * - ``mode``
+
+     - String that specifies whether the balancer thread is running
+       or stopped. Possible values are:
+
+       - "full"
+           Balancer thread is running but not necessarily in a
+           balancing round.
+
+       - "off"
+           Balancer thread is stopped. Chunk balancing cannot occur in
+           this mode.
+   
+   * - ``inBalancerRound``
+
+     - Boolean that specifies if the balancer is currently in a
+       balancing round.
+
+   * - ``numBalancerRounds``
+
+     - Number of balancer rounds which have occurred since the
+       config servers were started. This value is reset to 0 when 
+       the config servers are restarted.
+
+   * - ``ok``
+
+     - See :ref:`Command Response <command-response>`.
+
+   * - ``$clusterTime``
+
+     - See :ref:`Command Response <command-response>`.
+
+   * - ``operationTime``
 
-   Returns true if the :term:`balancer` process is currently running
-   and migrating chunks and false if the balancer process is not
-   running. Use :method:`sh.getBalancerState()` to determine if the
-   balancer is enabled or disabled.
+     - See :ref:`Command Response <command-response>`.
 
 .. seealso::
 

source/reference/sharding.txt

@@ -99,7 +99,7 @@ Sharding Methods in ``mongosh``
 
    * - :method:`sh.isBalancerRunning()`
 
-     - Returns a boolean to report if the balancer process is currently migrating chunks.
+     - Returns a document describing the status of the balancer.
 
    * - :method:`sh.moveChunk()`