[DOCS-130] Improve C++ Driver Documentation Created: 16/Feb/12  Updated: 23/Jun/16  Resolved: 19/Aug/14

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

Type: Task Priority: Minor - P4
Reporter: Michael Wieher Assignee: Unassigned
Resolution: Duplicate Votes: 3
Labels: doxygen
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

Linux I suppose


Issue Links:
Duplicate
duplicates DOCS-1779 C++ Driver documentation is not very ... Closed
duplicates DOCS-8158 C++ Driver Playbook Closed
is duplicated by DOCS-96 C++ driver documentation is too short... Closed
is duplicated by DOCS-512 Add date/time examples for c++ driver Closed
is duplicated by DOCS-492 Documentation on C++ driver does not ... Closed
Participants:
Days since reply: 11 years, 16 weeks, 1 day ago

 Description   

Hi,

I'm one of the (rare?) I guess users of the C++ driver and learning how to use it has been a nightmare.

Here's a list of issues I found:
--------------------------------
1. The file, bsondemo.cpp is not actually on github (or the mutlitude of links on mongodb.org do not point to it)

  • Almost all of your documentation points the user to this "example" - which does not exist.
    2. You should provide more examples, one common case is when a user is modifying an object in the database.
  • Querying, updating, inserting etc. that relate to the _id field are prolematic, as they rely on the user's use of mongo::OID object properly
    This has not been documented, there's no examples, and your doxygen docs are somewhat innacurate most of the time.
    Significant time to discover what should be a simple operation.
    3. More examples. There's a tiny splattering of 3-4 lines of code which infer a few simple use cases.
    4. The BSON_ARRRAY macro is barely documented at all.
  • example: How to create an empty BSON_ARRAY() object? ie: All examples assume that the BSON_ARRAY being created has an element. Trying:
    BSON_ARRAY()
    BSON_ARRAY([])
    vector<mongo::BSONElement> v; BSON_ARRAY(v)

None of those natural and intitive guesses work, but creation of an empty array is a pretty standard thing to do if you're setting up something to push data into.

5. work with someone to develop use cases for "new users" and try to document some of their common issues.
6. Review your mongodb.org page and where you see the page says, "This page documentation is out of date, but the general ideas hold" and actually update, once a user gets past the general concepts, we actually need to know syntax. Especially since none of it is documented.

7. review zeroMQ's "the guide" as an example of decent documentation, examples in multiple languages, and a relatively complete attempt to anticipate the pitfalls new users would run into and provide reasonable information to them.



 Comments   
Comment by Daniel Pasette (Inactive) [ 30/Oct/12 ]

Including a long thread for reference on building the C++ driver in windows: https://groups.google.com/forum/?fromgroups=#!topic/mongodb-dev/7ahv1GiaV24

Comment by Plug Gulp [ 01/Sep/12 ]

This is a very important ticket. For e.g. I am looking for examples on how to use serialization and deserialization of objects and don't see any! Please could you expedite this ticket? mongodb is written in C+, hence providing documentation for C+ driver should be relatively easy. The least that can be done is to provide examples in the doxygen generated document itself - i.e. each class should contain source example in C++ on how to use is.

Thanks and regards,

Plug

PS: For inspiration please look at Qt documentation.

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