[CXX-2582] Docs: Tutorial Improvement Suggestions Created: 27/Sep/22  Updated: 07/Feb/24  Resolved: 13/Mar/23

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.7.1

Type: Task Priority: Unknown
Reporter: Steve Silvester Assignee: Kevin Albertson
Resolution: Fixed Votes: 0
Labels: buildfest-2022
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Quarter: FY24Q1

 Description   

Re: https://mongocxx.org/mongocxx-v3/tutorial/

"You can obtain this value using the inserted_ids() method of the returned mongocxx::result::insert_many instance" - It would be helpful to give an example here.

In the "Access a Collection" section, we should use the variable name collection, since that is used for the rest of the tutorial.

Ideally the names of the results would all be unique, such as delete_result, so you do not have to rename them yourself to prevent collisions.

These changes would make it easier to follow along by copy/pasting and running the code incrementally.



 Comments   
Comment by Githook User [ 14/Mar/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CXX-2582 revise tutorial (#940)

  • remove outdated comment

CXX-894 is resolved

  • remove libmongoc and libbson include headers

It is not output by pkg-config for libmongocxx and is not necessary for an application

  • fix rendering of invalid JSON

The invalid JSON values are rendered highlighted in black.

  • add initial tutorial
  • rename `coll` to `collection`
  • use `collection`, not `restaurants`
  • use `string_view`, not `string`

Fixes `error: no member named 'to_string' in 'std::string_view'`

  • use `view`, not `doc`
  • use `auto`
  • distinguish result variables
  • show example of getting insert ids

This is requested in the ticket.

  • add scopes and comments
  • use inline document
  • replace stream builder with basic builder

Use of the stream builder is documented as discouraged.
The basic builder syntax is more succinct.

  • make less documents

To shorten the output

  • drop collection to clean up
  • rename `view` to `doc_view`
  • add assertions on unused variables

To fix `-Wunused-variable` warnings

  • assert writes return results

This is the default behavior unless overridden with an unacknowledged write concern.

  • update "versions" array to reflect supported versions

C++ driver 3.7.0 depends on C driver 1.22.1.
C driver 1.22.1 supports MongoDB versions 3.6+.
The docs compatibility table here is incorrect: https://www.mongodb.com/docs/drivers/cxx/#mongodb-compatibility

  • fix assert
  • use only three documents in tutorial

To further simplify example.

  • use assert instead of printing
  • add example of printing all documents
  • remove TODO comment
  • remove whitespace
  • note requirement of get_utf8 in C++ driver < 3.7.0
  • apply changes to tutorial.md
  • fix assert define check
  • move redefinition of `assert` macro

Release builds may undefine the assert macro and result
in -Wunused-variable warnings.

  • Update docs/content/mongocxx-v3/tutorial.md

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>

---------

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>
Branch: releases/stable
https://github.com/mongodb/mongo-cxx-driver/commit/a94ee660b66a511528a927c8ed8da5d111d5fc9d

Comment by Githook User [ 13/Mar/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CXX-2582 revise tutorial (#940)

  • remove outdated comment

CXX-894 is resolved

  • remove libmongoc and libbson include headers

It is not output by pkg-config for libmongocxx and is not necessary for an application

  • fix rendering of invalid JSON

The invalid JSON values are rendered highlighted in black.

  • add initial tutorial
  • rename `coll` to `collection`
  • use `collection`, not `restaurants`
  • use `string_view`, not `string`

Fixes `error: no member named 'to_string' in 'std::string_view'`

  • use `view`, not `doc`
  • use `auto`
  • distinguish result variables
  • show example of getting insert ids

This is requested in the ticket.

  • add scopes and comments
  • use inline document
  • replace stream builder with basic builder

Use of the stream builder is documented as discouraged.
The basic builder syntax is more succinct.

  • make less documents

To shorten the output

  • drop collection to clean up
  • rename `view` to `doc_view`
  • add assertions on unused variables

To fix `-Wunused-variable` warnings

  • assert writes return results

This is the default behavior unless overridden with an unacknowledged write concern.

  • update "versions" array to reflect supported versions

C++ driver 3.7.0 depends on C driver 1.22.1.
C driver 1.22.1 supports MongoDB versions 3.6+.
The docs compatibility table here is incorrect: https://www.mongodb.com/docs/drivers/cxx/#mongodb-compatibility

  • fix assert
  • use only three documents in tutorial

To further simplify example.

  • use assert instead of printing
  • add example of printing all documents
  • remove TODO comment
  • remove whitespace
  • note requirement of get_utf8 in C++ driver < 3.7.0
  • apply changes to tutorial.md
  • fix assert define check
  • move redefinition of `assert` macro

Release builds may undefine the assert macro and result
in -Wunused-variable warnings.

  • Update docs/content/mongocxx-v3/tutorial.md

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>

---------

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>
Branch: releases/v3.7
https://github.com/mongodb/mongo-cxx-driver/commit/a94ee660b66a511528a927c8ed8da5d111d5fc9d

Comment by Githook User [ 13/Mar/23 ]

Author:

{'name': 'Kevin Albertson', 'email': 'kevin.albertson@mongodb.com', 'username': 'kevinAlbs'}

Message: CXX-2582 revise tutorial (#940)

  • remove outdated comment

CXX-894 is resolved

  • remove libmongoc and libbson include headers

It is not output by pkg-config for libmongocxx and is not necessary for an application

  • fix rendering of invalid JSON

The invalid JSON values are rendered highlighted in black.

  • add initial tutorial
  • rename `coll` to `collection`
  • use `collection`, not `restaurants`
  • use `string_view`, not `string`

Fixes `error: no member named 'to_string' in 'std::string_view'`

  • use `view`, not `doc`
  • use `auto`
  • distinguish result variables
  • show example of getting insert ids

This is requested in the ticket.

  • add scopes and comments
  • use inline document
  • replace stream builder with basic builder

Use of the stream builder is documented as discouraged.
The basic builder syntax is more succinct.

  • make less documents

To shorten the output

  • drop collection to clean up
  • rename `view` to `doc_view`
  • add assertions on unused variables

To fix `-Wunused-variable` warnings

  • assert writes return results

This is the default behavior unless overridden with an unacknowledged write concern.

  • update "versions" array to reflect supported versions

C++ driver 3.7.0 depends on C driver 1.22.1.
C driver 1.22.1 supports MongoDB versions 3.6+.
The docs compatibility table here is incorrect: https://www.mongodb.com/docs/drivers/cxx/#mongodb-compatibility

  • fix assert
  • use only three documents in tutorial

To further simplify example.

  • use assert instead of printing
  • add example of printing all documents
  • remove TODO comment
  • remove whitespace
  • note requirement of get_utf8 in C++ driver < 3.7.0
  • apply changes to tutorial.md
  • fix assert define check
  • move redefinition of `assert` macro

Release builds may undefine the assert macro and result
in -Wunused-variable warnings.

  • Update docs/content/mongocxx-v3/tutorial.md

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>

---------

Co-authored-by: Roberto C. Sánchez <roberto@connexer.com>
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/6af37f81dfc64d1bcd33b993515a7c50e83654bb

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