Improve documentation briefs and misc. details (#1311)

Author: eramongodb

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/value.hpp

@@ -29,9 +29,10 @@ namespace v_noabi {
 namespace array {
 
 ///
-/// A read-only BSON array that owns its underlying buffer. When a array::value goes
-/// out of scope, the underlying buffer is freed. Generally this class should be used
-/// sparingly; array::view should be used instead wherever possible.
+/// A read-only BSON array that owns its underlying buffer.
+///
+/// When a array::value goes out of scope, the underlying buffer is freed. Generally this class
+/// should be used sparingly; array::view should be used instead wherever possible.
 ///
 class value {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_array.hpp

@@ -35,8 +35,11 @@ void value_append(core* core, T&& t);
 } // namespace impl
 
 ///
-/// An internal class of builder::basic.
-/// Users should almost always construct a builder::basic::array instead.
+/// Represents an array element being constructed during an append operation.
+///
+/// @see
+/// - @ref bsoncxx::v_noabi::builder::basic::array
+/// - @ref bsoncxx::v_noabi::builder::basic::document
 ///
 class sub_array {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_document.hpp

@@ -37,8 +37,11 @@ void value_append(core* core, T&& t);
 } // namespace impl
 
 ///
-/// An internal class of builder::basic.
-/// Users should almost always construct a builder::basic::document instead.
+/// Represents a document element being constructed during an append operation.
+///
+/// @see
+/// - @ref bsoncxx::v_noabi::builder::basic::array
+/// - @ref bsoncxx::v_noabi::builder::basic::document
 ///
 class sub_document {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/closed_context.hpp

@@ -25,11 +25,11 @@ namespace builder {
 namespace stream {
 
 ///
-/// The closed_context, when used as a template parameter for array_context,
-/// value_context or key_context, indicates that the document cannot be closed
-/// further. This could indicate that the document is the root, or that the type
-/// stack has been intentionally erased, as is the case when using callbacks in
-/// the stream api.
+/// Indicates the document being constructed cannot be closed further.
+///
+/// Used as a template parameter for array_context, value_context or key_context. This could
+/// indicate that the document is the root, or that the type stack has been intentionally erased, as
+/// is the case when using callbacks in the stream api.
 ///
 struct closed_context {
     closed_context(core*) {}

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/key_context.hpp

@@ -30,8 +30,9 @@ namespace builder {
 namespace stream {
 
 ///
-/// A stream context which expects a key, which can later be followed by
-/// value, then more key/value pairs.
+/// A stream context which expects a key.
+///
+/// This can later be followed by value, then more key/value pairs.
 ///
 /// The template argument can be used to hold additional information about
 /// containing documents or arrays. I.e. value_context<> implies that this

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/value_context.hpp

@@ -30,8 +30,9 @@ namespace builder {
 namespace stream {
 
 ///
-/// A stream context which expects a value, which can later be followed by
-/// more key/value pairs.
+/// A stream context which expects a value.
+///
+/// This can later be followed by more key/value pairs.
 ///
 /// The template argument can be used to hold additional information about
 /// containing documents or arrays. I.e. value_context<> implies that this

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/decimal128.hpp

@@ -27,7 +27,15 @@ namespace bsoncxx {
 namespace v_noabi {
 
 ///
-/// Represents an IEEE 754-2008 BSON Decimal128 value in a platform-independent way.
+/// Represents a MongoDB BSON Decimal128.
+///
+/// This type implements the Decimal Arithmetic Encodings (IEEE 754-2008) specification, _with certain
+/// exceptions_ around value integrity and the coefficient encoding. When a value cannot be represented exactly, the
+/// value will be rejected.
+///
+/// @see
+/// - [BSON Types (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/bson-types/)
+/// - [BSON Decimal128 (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/bson-decimal128/decimal128/)
 ///
 class decimal128 {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/document/value.hpp

@@ -31,9 +31,10 @@ namespace v_noabi {
 namespace document {
 
 ///
-/// A read-only BSON document that owns its underlying buffer. When a document::value goes
-/// out of scope, the underlying buffer is freed. Generally this class should be used
-/// sparingly; document::view should be used instead wherever possible.
+/// A read-only BSON document that owns its underlying buffer.
+///
+/// When a document::value goes out of scope, the underlying buffer is freed. Generally this class
+/// should be used sparingly; document::view should be used instead wherever possible.
 ///
 class value {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/exception/exception.hpp

@@ -28,8 +28,7 @@ BSONCXX_DISABLE_WARNING(MSVC(4251));
 BSONCXX_DISABLE_WARNING(MSVC(4275));
 
 ///
-/// Class representing any exceptions emitted from the bsoncxx library or
-/// its underlying implementation.
+/// Base class for all exceptions thrown by the bsoncxx library unless otherwise specified.
 ///
 class exception : public std::system_error {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/oid.hpp

@@ -28,15 +28,10 @@ namespace bsoncxx {
 namespace v_noabi {
 
 ///
-/// Represents a MongoDB ObjectId. As this BSON type is used within the MongoDB server
-/// as a primary key for each document, it is useful for representing a 'pointer'
-/// to another document.
-///
-/// @note we use 'oid' to refer to this concrete class. We use 'ObjectId' to refer
-/// to the BSON type.
+/// Represents a MongoDB BSON ObjectId.
 ///
 /// @see
-/// - https://www.mongodb.com/docs/manual/reference/object-id/
+/// - [BSON Types (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/bson-types/)
 ///
 class oid {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/string/view_or_value.hpp

@@ -28,7 +28,7 @@ namespace v_noabi {
 namespace string {
 
 ///
-/// Class representing a view-or-value variant type for strings.
+/// A view-or-value variant type for strings.
 ///
 /// @par Derived From
 /// - @ref bsoncxx::v_noabi::view_or_value<stdx::string_view, std::string>

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp

@@ -34,9 +34,10 @@ namespace types {
 namespace bson_value {
 
 ///
-/// A variant owning type that represents any BSON type. Owns its underlying
-/// buffer. When a bson_value::value goes out of scope, its underlying
-/// buffer is freed.
+/// An owning variant type that represents any BSON type.
+///
+/// Owns its underlying buffer. When a bson_value::value goes out of scope, its underlying buffer is
+/// freed.
 ///
 /// For accessors into this type and to extract the various BSON types out,
 /// please use bson_value::view.

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/view.hpp

@@ -44,8 +44,9 @@ namespace bsoncxx {
 namespace v_noabi {
 namespace types {
 namespace bson_value {
+
 ///
-/// A view-only variant that can contain any BSON type.
+/// A non-owning variant that can contain any BSON type.
 ///
 /// @warning
 ///   Calling the wrong get_<type> method will cause an exception

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/validate.hpp

@@ -72,8 +72,7 @@ validate(
     std::size_t* invalid_offset = nullptr);
 
 ///
-/// A validator is used to enable or disable specific checks that can be
-/// performed during BSON validation.
+/// Used to toggle checks which may be performed during BSON validation.
 ///
 class validator {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/view_or_value.hpp

@@ -26,7 +26,7 @@ namespace bsoncxx {
 namespace v_noabi {
 
 ///
-/// Class representing a view-or-value variant type.
+/// A view-or-value variant type.
 ///
 template <typename View, typename Value>
 class view_or_value {
@@ -35,12 +35,12 @@ class view_or_value {
     using value_type = Value;
 
     ///
-    /// Class View must be constructible from an instance of class Value.
+    /// View must be constructible from an instance of class Value.
     ///
     static_assert(std::is_constructible<View, Value>::value, "View type must be constructible from a Value");
 
     ///
-    /// Class View must be default constructible.
+    /// View must be default constructible.
     ///
     static_assert(std::is_default_constructible<View>::value, "View type must be default constructible");
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/bulk_write.hpp

@@ -28,7 +28,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing a batch of write operations that can be sent to the server as a group.
+/// A batch of write operations that can be sent to the server as a group.
 ///
 /// If you have a lot of write operations to execute, it can be more efficient to send them as
 /// part of a bulk_write in order to avoid unnecessary network-level round trips between the driver

src/mongocxx/include/mongocxx/v_noabi/mongocxx/change_stream.hpp

@@ -30,7 +30,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing a MongoDB change stream.
+/// A MongoDB change stream.
 ///
 class change_stream {
    public:
@@ -124,7 +124,7 @@ class change_stream {
 };
 
 ///
-/// Class representing a MongoDB change stream iterator.
+/// A MongoDB change stream iterator.
 ///
 class change_stream::iterator {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client.hpp

@@ -41,7 +41,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing a client connection to MongoDB.
+/// A client connection to a MongoDB server.
 ///
 /// Acts as a logical gateway for working with databases contained within a MongoDB server.
 ///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_encryption.hpp

@@ -37,7 +37,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class supporting operations for MongoDB Client-Side Field Level Encryption.
+/// Supports MongoDB Client-Side Field Level Encryption operations.
 ///
 class client_encryption {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_session.hpp

@@ -35,6 +35,8 @@
 namespace mongocxx {
 namespace v_noabi {
 
+///
+/// Supports MongoDB client session operations.
 ///
 /// Use a session for a sequence of operations, optionally with either causal consistency
 /// or snapshots.

src/mongocxx/include/mongocxx/v_noabi/mongocxx/collection.hpp

@@ -71,7 +71,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing server side document groupings within a MongoDB database.
+/// A MongoDB collection.
 ///
 /// Collections do not require or enforce a schema and documents inside of a collection can have
 /// different fields. While not a requirement, typically documents in a collection have a similar

src/mongocxx/include/mongocxx/v_noabi/mongocxx/cursor.hpp

@@ -33,7 +33,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing a pointer to the result set of a query on a MongoDB server.
+/// A cursor over the documents returned by a query to a MongoDB server.
 ///
 /// Clients can iterate through a cursor::iterator to retrieve results.
 ///
@@ -104,7 +104,7 @@ class cursor {
 };
 
 ///
-/// Class representing an input iterator of documents in a MongoDB cursor
+/// An input iterator of documents in a MongoDB cursor
 /// result set.
 ///
 /// All non-end iterators derived from the same mongocxx::v_noabi::cursor move in

src/mongocxx/include/mongocxx/v_noabi/mongocxx/database.hpp

@@ -38,7 +38,7 @@ namespace mongocxx {
 namespace v_noabi {
 
 ///
-/// Class representing a MongoDB database.
+/// A MongoDB database.
 ///
 /// Acts as a gateway for accessing collections that are contained within a database. It inherits
 /// all of its default settings from the client that creates it.

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_failed_event.hpp

@@ -29,10 +29,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver fails to execute a MongoDB command.
+/// The failed execution of a MongoDB command.
 ///
 /// @see
-/// - "CommandFailedEvent" in https://github.com/mongodb/specifications/blob/master/source/command-logging-and-monitoring/command-logging-and-monitoring.md
+/// - [Command Logging and Monitoring (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/command-logging-and-monitoring/command-logging-and-monitoring/)
 ///
 class command_failed_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_started_event.hpp

@@ -29,10 +29,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver begins executing a MongoDB command.
+/// The start of the execution of a MongoDB command.
 ///
 /// @see
-/// - "CommandStartedEvent" in https://github.com/mongodb/specifications/blob/master/source/command-logging-and-monitoring/command-logging-and-monitoring.md
+/// - [Command Logging and Monitoring (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/command-logging-and-monitoring/command-logging-and-monitoring/)
 ///
 class command_started_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_succeeded_event.hpp

@@ -29,10 +29,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver successfully executes a MongoDB command.
+/// The successful execution of a MongoDB command.
 ///
 /// @see
-/// - "CommandSucceededEvent" in https://github.com/mongodb/specifications/blob/master/source/command-logging-and-monitoring/command-logging-and-monitoring.md
+/// - [Command Logging and Monitoring (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/command-logging-and-monitoring/command-logging-and-monitoring/)
 ///
 class command_succeeded_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/heartbeat_failed_event.hpp

@@ -28,11 +28,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver failed to send an "hello" command to check the
-/// status of a server.
+/// The failed execution of a heartbeat ("hello") command.
 ///
 /// @see
-/// - "ServerHeartbeatFailedEvent" in https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md
+/// - [SDAM Logging and Monitoring Specification (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring/)
 ///
 class heartbeat_failed_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/heartbeat_started_event.hpp

@@ -27,11 +27,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver begins executing a "hello" command to check the
-/// status of a server.
+/// The start of the execution of a heartbeat ("hello") command.
 ///
 /// @see
-/// - "ServerHeartbeatStartedEvent" in https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md
+/// - [SDAM Logging and Monitoring Specification (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring/)
 ///
 class heartbeat_started_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/heartbeat_succeeded_event.hpp

@@ -26,11 +26,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver completes a "hello" command to check the status
-/// of a server.
+/// The successful execution of a heartbeat ("hello") command.
 ///
 /// @see
-/// - "ServerHeartbeatSucceededEvent" in https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md
+/// - [SDAM Logging and Monitoring Specification (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring/)
 ///
 class heartbeat_succeeded_event {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/server_changed_event.hpp

@@ -28,11 +28,10 @@ namespace v_noabi {
 namespace events {
 
 ///
-/// An event notification sent when the driver observes a change in the status of a server it is
-/// connected to.
+/// A change in the description of a connected MongoDB server.
 ///
 /// @see
-/// - "ServerDescriptionChangedEvent" in https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md
+/// - [SDAM Logging and Monitoring Specification (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring/)
 ///
 class server_changed_event {
    public: