[CXX-482] Please make docs for C, C++ drivers match docs for Java driver Created: 21/Jan/15  Updated: 23/Jan/15  Resolved: 23/Jan/15

Status: Closed
Project: C++ Driver
Component/s: None
Affects Version/s: None
Fix Version/s: legacy-1.0.0-rc4

Type: Improvement Priority: Major - P3
Reporter: Mark Callaghan Assignee: Andrew Morrow (Inactive)
Resolution: Done Votes: 0
Labels: legacy-cxx
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
is duplicated by CXX-484 Generate documentation for 26compat r... Closed
is duplicated by CXX-485 Update testing wiki page Closed

 Description   

I wanted to write MongoDB benchmark clients in C++ to avoid problems from Java GC stalls and to re-learn modern C++.

For the C driver the API section documents types but not functions.
http://api.mongodb.org/c/current/?_ga=1.108812482.1512114027.1402327973

For the C++ driver I get confused.

  • there is the "legacy" driver and the "26compat" driver but sometimes the 26compat driver is described as the legacy-26compat driver. And the name "26compat" makes me think there isn't a version for use with 2.8
  • the API page doesn't have anything for 26compat – http://api.mongodb.org/cxx/?_ga=1.82181590.1512114027.1402327973
  • the wiki page could use more sections for 26compat (testing)


 Comments   
Comment by Andrew Morrow (Inactive) [ 22/Jan/15 ]

mdcallag FYI I've added some notes to the testing wiki page explaining the differences on the 26compat branch. See the linked wiki diff in CXX-485 for changes.

Comment by Andrew Morrow (Inactive) [ 22/Jan/15 ]

mdcallag Since I've filed other tickets for the issues with the C++ Driver 26compat docs (CXX-484) and the outdated wiki (CXX-485), I'm going to close this ticket tomorrow, unless you have a specific reason you would like it kept open, in which case please just let me know.

Thanks,
Andrew

Comment by Mark Callaghan [ 21/Jan/15 ]

Thanks for the prompt responses. I see now that the C API has lots of documentation once I click on the types.

Comment by Andrew Morrow (Inactive) [ 21/Jan/15 ]

Hi mdcallag -

A few comments in addition to what Tyler wrote above:

  • As Tyler mentioned, the C driver documentation organizes the functions by the principle type on which the functions operate.
  • I agree the documentation for the 26compat stream is not ideal. I've filed a ticket to generate separate documentation, not pointing into the outdated server docs, for the next 26compat point release. Watch CXX-484, and when that closes the relevant docs should be available along side the documentation for the legacy release stream. In the meantime, the following link should reflect the contents of 26compat very closely: http://api.mongodb.org/cplusplus/2.6.1/
  • I've filed CXX-485 to improve the wiki page re testing. That page is out of date with respect to both the 26compat branch and the legacy branch, so clearly could use some attention.

In the meantime, if you have specific questions that the documentation is not answering, the C and C++ developers monitor mongodb-user and mongodb-dev closely and will be happy to answer any questions there.

Thanks,
Andrew

Comment by Michael Paik [ 21/Jan/15 ]

To be clear, this isn't actually from me - this is a DOCS ticket that I moved to Drivers that Bernie then moved to C++. I've got no skin in the game.

Comment by Tyler Brock [ 21/Jan/15 ]

Hey Michael,

That seems like a worthwhile goal. Thanks for being interested.

This project is for the C++ drivers only. Any questions about the C driver should be filed as within the CDRIVER project. I would file a ticket there myself for your issue but I'm not sure I understand what you mean by "the C driver api section documents types but not functions". The existing documentation does, in fact, document functions but they are documented within the section for a specific type. For example, the documentation for mongoc_collection_t includes documentation for mongoc_collection_insert which operates on a mongoc_collection_t.

The C++ driver is confusing. There are 3 of them, one which is called 26compat, another called legacy, and the future one which will just be called "The C++(11) driver". The 26compat driver is meant to be 2.6compat-ible and was extracted directly from the MongoDB 2.6 source tree. The legacy driver has various enhancements to that code while maintaining the overall API and cruft of the existing driver and the new C++11 driver is brand new and being written from scratch.

We are encouraging users to use the legacy driver now and the C++11 driver when it is released (hence the name legacy for the existing one).

The API page does document the 26compat driver as C++(Server) – Deprecated.

We probably won't update the wiki page for 26compat as we don't want people to actually use it outside of requiring a drop in replacement for code written against the client that existed in the server circa MongoDB 2.6.

Generated at Wed Feb 07 21:59:20 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.