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: