[CXX-1196] Improve mongocxx::instance documentation Created: 20/Jan/17  Updated: 07/Mar/17  Resolved: 07/Mar/17

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.2.0-rc0

Type: Bug Priority: Major - P3
Reporter: J Rassi Assignee: Samuel Rossi (Inactive)
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to CXX-890 Add an example that shows how to mana... Closed
is related to CXX-1224 mongocxx::client constructor fails on... Closed
is related to CXX-1197 Client and pool initialization should... Backlog
is related to CXX-958 Am I supposed to create the instance/... Closed

 Description   

mongocxx::instance is under-documented and difficult to use correctly. We should make the following improvements to our documentation of mongocxx::instance:

  • The mongocxx "Quick Start" page under "Tutorial for mongocxx" does not mention mongocxx::instance. We should add a section which explains what mongocxx::instance is, and also makes a recommendation to users on how to manage this object.
  • All mongocxx examples should contain a code comment indicating that creating a mongocxx::instance object is necessary to initialize the driver.
  • The class comment for instance.hpp should be expanded. In particular, it should:
    • Indicate explicitly that the mongocxx::instance constructor initializes the driver and that mongocxx::instance destructor shuts down the driver.
    • Explain that instantiating mongocxx::instance more than once in the same program is an error (even if the objects have non-overlapping lifetimes).
    • Contain a short example of basic correct usage of mongocxx::instance.
    • Contain an example of common incorrect usage of mongocxx::instance.
    • Refer users to the "instance_management" example for advanced mongocxx::instance usage.


 Comments   
Comment by Githook User [ 07/Mar/17 ]

Author:

{'email': 'saghmrossi@gmail.com', 'username': 'saghm', 'name': 'Saghm Rossi'}

Message: CXX-1196 Improve mongocxx::instance documentation
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/8b81c5e1c16651f75c756cac9e76837f0e293a60

Comment by Githook User [ 07/Mar/17 ]

Author:

{u'username': u'saghm', u'name': u'Saghm Rossi', u'email': u'saghmrossi@gmail.com'}

Message: CXX-1196 Improve mongocxx::instance documentation
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/8b81c5e1c16651f75c756cac9e76837f0e293a60

Comment by J Rassi [ 22/Feb/17 ]

Per a discussion with Bernie from last week, I'm going to re-open this ticket and expand its scope to cover the examples, and the instance class comment, too. Thanks for addressing the tutorial, Sam.

Comment by Githook User [ 22/Feb/17 ]

Author:

{u'username': u'saghm', u'name': u'Saghm Rossi', u'email': u'saghmrossi@gmail.com'}

Message: CXX-1196: "Tutorial for mongocxx" needs to explain mongocxx::instance
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/bb39a41bc262587772dc5a03552467dbf49b8878

Generated at Wed Feb 07 22:01:43 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.