[CXX-1530] Ensure example code is consistent with docs processes Created: 19/Mar/18  Updated: 28/Oct/23  Resolved: 03/Sep/20

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.7.0, 3.7.0-beta1

Type: Improvement Priority: Major - P3
Reporter: Ryan Timmons Assignee: Roberto Sanchez
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related

 Description   

(Mostly copy/pasted from https://mongodbcr.appspot.com/189650001/)

Investigate which code in examples/ is actually used in documentation and ensure that unused examples are either used, merged with used examples, or deleted?

Long ago the C++ driver team was asked to write examples as part of the 'rosetta stone' of drivers examples. We didn't like that we were supposed to write those in a way that was disconnected to the repo (e.g. just as docs).

So we put in annotations so we could have the docs team auto-extract them, and that way if we changed them in the code they would be updated.

I don't know what happened with all of that, but we were annotating examples as follows:

https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/query.cpp#L42 https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/query.cpp#L47

Then it appears that at some point this work was lost, and then done again, under the mongodb.com/documentation_examples.cpp file:

https://github.com/mongodb/mongo-cxx-driver/blob/master/examples/mongocxx/mongodb.com/documentation_examples.cpp#L36

If the new files under mongodb.com are the right way to do it, then we should at least strip out the old annotations? I'm also puzzled about why that prior art got lost in the shuffle.



 Comments   
Comment by Githook User [ 03/Sep/20 ]

Author:

{'name': 'Roberto C. Sánchez', 'email': 'roberto@connexer.com', 'username': 'rcsanchez97'}

Message: CXX-1530 remove unused example comment annotations (#710)
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/4e9fcfd32b76c8d7c75482cdec4aa3681eb7a204

Comment by A. Jesse Jiryu Davis [ 11/Apr/18 ]

Let's include example code in rendered C++ Driver docs, too, not just the MongoDB Manual. At that time, reconsider how to check the server version for which examples to run, e.g. the change stream example requires a MongoDB 3.6+ replica set and soon a transaction example will require a 4.0+ replica set.

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