CXX-796 Improve bsoncxx doc comments

Replaced doc todo's under bsoncxx with doc comments.

Author: hanumantmk

src/bsoncxx/array/element.hpp

@@ -27,7 +27,11 @@ BSONCXX_INLINE_NAMESPACE_BEGIN
 namespace array {
 
 ///
-/// @todo document this class
+/// A variant view type that accesses values in serialized BSON arrays.
+///
+/// Element functions as a variant type, where the kind of the element can be
+/// interrogated by calling type() and a specific value can be extracted through
+/// get_X() accessors.
 ///
 class BSONCXX_API element : private document::element {
    public:

src/bsoncxx/array/value.hpp

@@ -83,7 +83,9 @@ class BSONCXX_API value {
     BSONCXX_INLINE array::view view() const noexcept;
 
     ///
-    /// @todo document this method
+    /// Conversion operator that provides a view given a value.
+    ///
+    /// @return A view over the value.
     ///
     BSONCXX_INLINE operator array::view() const noexcept;
 

src/bsoncxx/array/view.hpp

@@ -141,7 +141,10 @@ class BSONCXX_API view {
 };
 
 ///
-/// @todo document this class
+/// A mutable iterator over the contents of an array view.
+///
+/// This iterator type provides a mutable forward iterator interface to array
+/// view elements.
 ///
 class BSONCXX_API view::iterator : public std::iterator<std::forward_iterator_tag, element> {
    public:
@@ -172,7 +175,10 @@ class BSONCXX_API view::iterator : public std::iterator<std::forward_iterator_ta
 };
 
 ///
-/// @todo document this class
+/// A const iterator over the contents of an array view.
+///
+/// This iterator type provides a const forward iterator interface to array
+/// view elements.
 ///
 class BSONCXX_API view::const_iterator
     : public std::iterator<std::forward_iterator_tag, element, std::ptrdiff_t, const element*,

src/bsoncxx/builder/basic/array.hpp

@@ -49,7 +49,10 @@ class array : public sub_array {
     }
 
     ///
-    /// @todo document this method
+    /// Conversion operator that provides a view of the current builder
+    /// contents.
+    ///
+    /// @return A view of the current builder contents.
     ///
     BSONCXX_INLINE operator bsoncxx::array::view() const {
         return view();

src/bsoncxx/builder/basic/document.hpp

@@ -47,7 +47,10 @@ class document : public sub_document {
     }
 
     ///
-    /// @todo document this method
+    /// Conversion operator that provides a view of the current builder
+    /// contents.
+    ///
+    /// @return A view of the current builder contents.
     ///
     BSONCXX_INLINE operator bsoncxx::document::view() const {
         return view();

src/bsoncxx/builder/basic/sub_array.hpp

@@ -55,7 +55,7 @@ class BSONCXX_API sub_array {
     }
 
     ///
-    /// @todo document this method
+    /// Inductive base-case for the variadic append(...)
     ///
     BSONCXX_INLINE
     void append() {

src/bsoncxx/builder/basic/sub_document.hpp

@@ -50,7 +50,7 @@ class BSONCXX_API sub_document {
     }
 
     ///
-    /// @todo document this method
+    /// Inductive base-case for the variadic append(...)
     ///
     BSONCXX_INLINE
     void append() {

src/bsoncxx/builder/concatenate.hpp

@@ -35,14 +35,20 @@ struct concatenate_doc {
     BSONCXX_INLINE ~concatenate_doc() = default;
 
     ///
-    /// @todo document this method
+    /// Conversion operator that provides a view of the wrapped concatenate
+    /// document.
+    ///
+    /// @return A view of the wrapped concatenate document.
     ///
     BSONCXX_INLINE operator document::view() const {
         return doc;
     }
 
     ///
-    /// @todo document this method
+    /// Accessor that provides a view of the wrapped concatenate
+    /// document.
+    ///
+    /// @return A view of the wrapped concatenate document.
     ///
     BSONCXX_INLINE document::view view() const {
         return doc;
@@ -61,14 +67,20 @@ struct concatenate_array {
     BSONCXX_INLINE ~concatenate_array() = default;
 
     ///
-    /// @todo document this method
+    /// Conversion operator that provides a view of the wrapped concatenate
+    /// array.
+    ///
+    /// @return A view of the wrapped concatenate array.
     ///
     BSONCXX_INLINE operator array::view() const {
         return array;
     }
 
     ///
-    /// @todo document this method
+    /// Accessor that provides a view of the wrapped concatenate
+    /// array.
+    ///
+    /// @return A view of the wrapped concatenate array.
     ///
     BSONCXX_INLINE array::view view() const {
         return array;

src/bsoncxx/builder/stream/array_context.hpp

@@ -34,26 +34,44 @@ class key_context;
 class single_context;
 
 ///
-/// An internal class of builder::stream. Users should not use this directly.
+/// A stream context which expects any number of values.
+///
+/// The template argument can be used to hold additional information about
+/// containing documents or arrays. I.e. value_context<> implies that this array
+/// is a sub_array in a document, while array_context would indicated a sub_array
+/// in an array. These types can be nested, such that contextual parsing (for
+/// key/value pairs) and depth (to prevent an invalid array_close) are enforced
+/// by the type system.
+///
+/// I.e.
+/// builder << array_context << array_context << ...;
+///
+/// This builds a bson array with successively higher index keys
 ///
 template <class base = closed_context>
 class array_context {
    public:
 
     ///
-    /// @todo document this method
+    /// Create an array_context given a core builder
+    ///
+    /// @param core
+    ///   The core builder to orchestrate
     ///
     BSONCXX_INLINE array_context(core* core) : _core(core) {
     }
 
     ///
-    /// @todo document this method
+    /// << operator for accepting a real value and appending it to the core
+    ///   builder.
+    ///
+    /// @param t
+    ///   The value to append
     ///
     template <class T>
     BSONCXX_INLINE typename std::enable_if<
         !(util::is_functor<T, void(array_context<>)>::value ||
           util::is_functor<T, void(single_context)>::value ||
-          std::is_same<T, const close_document_type>::value ||
           std::is_same<typename std::remove_reference<T>::type, const finalize_type>::value),
         array_context>::type&
     operator<<(T&& t) {
@@ -62,7 +80,12 @@ class array_context {
     }
 
     ///
-    /// @todo document this method
+    /// << operator for accepting a callable of the form void(array_context) or
+    ///   void(single_context) and invoking it to perform 1 or more value appends
+    ///   to the core builder.
+    ///
+    /// @param func
+    ///   The callback to invoke
     ///
     template <typename Func>
     BSONCXX_INLINE typename std::enable_if<(util::is_functor<Func, void(array_context<>)>::value ||
@@ -74,7 +97,15 @@ class array_context {
     }
 
     ///
-    /// @todo document this method
+    /// << operator for finalizing the stream.
+    ///
+    /// This operation finishes all processing necessary to fully encode the
+    /// bson bytes and returns an owning value.
+    ///
+    /// @param _
+    ///   A finalize_type token
+    ///
+    /// @return A value type which holds the complete bson document.
     ///
     template <typename T>
     BSONCXX_INLINE typename std::enable_if<
@@ -88,46 +119,64 @@ class array_context {
     }
 
     ///
-    /// @todo document this method
+    /// << operator for opening a new subdocument in the core builder.
+    ///
+    /// @param _
+    ///   An open_document_type token
     ///
     BSONCXX_INLINE key_context<array_context> operator<<(const open_document_type) {
         _core->open_document();
         return wrap_document();
     }
 
     ///
-    /// @todo document this method
+    /// << operator for concatenating another array.
+    ///
+    /// This operation concatenates all of the values from the passed document
+    /// into the current stream. Keys are adjusted to match the existing array.
+    ///
+    /// @param array
+    ///   An array to concatenate
     ///
     BSONCXX_INLINE array_context operator<<(concatenate_array array) {
         _core->concatenate(array.view());
         return *this;
     }
 
     ///
-    /// @todo document this method
+    /// << operator for opening a new subarray in the core builder.
+    ///
+    /// @param _
+    ///   An open_document_type token
     ///
     BSONCXX_INLINE array_context<array_context> operator<<(const open_array_type) {
         _core->open_array();
         return wrap_array();
     }
 
     ///
-    /// @todo document this method
+    /// << operator for closing a subarray in the core builder.
+    ///
+    /// @param _
+    ///   A close_array_type token
     ///
     BSONCXX_INLINE base operator<<(const close_array_type) {
         _core->close_array();
         return unwrap();
     }
 
     ///
-    /// @todo document this method
+    /// Conversion operator which provides a rooted array context given any
+    /// stream currently in a nested array_context.
     ///
     BSONCXX_INLINE operator array_context<>() {
         return array_context<>(_core);
     }
 
     ///
-    /// @todo document this method
+    /// Conversion operator for single_context.
+    ///
+    /// @relatesalso single_context
     ///
     BSONCXX_INLINE operator single_context();
 

src/bsoncxx/builder/stream/closed_context.hpp

@@ -25,7 +25,11 @@ class core;
 namespace stream {
 
 ///
-/// An internal struct of builder::stream. Users should not use this directly.
+/// 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.
 ///
 struct closed_context {
     closed_context(core*) {