[DOCS-1001] Clearly document which contingencies result in operation success or failure and what document will result in each case Created: 16/Jan/13  Updated: 30/Oct/23  Resolved: 27/Jul/16

Status: Closed
Project: Documentation
Component/s: manual
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Task Priority: Minor - P4
Reporter: eHarmony Matching Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
Related
Participants:
Days since reply: 7 years, 29 weeks ago

 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.



 Comments   
Comment by Emily Hall [ 27/Jul/16 ]

Closed by Emily Hall for Housekeeping on 7/27/16.
Please create a new ticket if for prioritization.

Thank you!

Comment by eHarmony Matching [ 16/Jan/13 ]

Note that the lack of this documentation of operation results is only a minor impediment to a human user typing in the mongo shell, because a person can intuit what the data mean. However, when developing applications or administrative automation, it is very important to have full and explicit documentation of this type.

Generated at Thu Feb 08 07:40:01 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.