Details
-
Task
-
Resolution: Won't Fix
-
Minor - P4
-
None
-
None
Description
The documentation for each command should include:
- the structure and contents of the return result in the event of success,
- which conditions cause failure,
- and the structure and contents of the result in the case of (each) failure.
Coarse-grained example: The docs for addShard (http://docs.mongodb.org/manual/reference/command/addShard/) do not include a description of the result at all. Most of the commands enumerated in http://docs.mongodb.org/manual/reference/commands/ and http://docs.mongodb.org/manual/reference/command/ have the same problem.
A longer example, in the shell this time, rs.status() (http://docs.mongodb.org/manual/reference/replica-status/): A replica set may be in the following states:
1. There is no replica set indicated in the configuration at all.
2. There is a replica set, but it has not been initiated yet.
3. A replica set has been initiated, but not all the nodes are up.
4. The nodes are up individually, but no primary has been elected yet.
5. The nodes are up, the election is finished; the RS is operational.
Calling rs.status() in either state (1) or (2) results in an error, although the docs do not indicate this. The structure of the resulting document in states (3)-(5) is fully documented. However, the structure of the "error document" is not documented at all.