Cleanup documentation

Author: osubboo

groups/bdl/bdlb/bdlb_arrayutil.h

@@ -155,6 +155,7 @@ BSLS_IDENT("$Id: $")
 // 2. The sequences are compared using the `mismatch` algorithm: To get the
 //    begin and of the `expect` array `bdlb::ArrayUtil::begin` and
 //    `bdlb::ArrayUtil::end`, respectively, are used.
+//
 // ```
 // void getAndCheckData(bool verbose)
 // {

groups/bdl/bdlb/bdlb_chartype.h

@@ -293,9 +293,9 @@ BSLS_IDENT("$Id: $")
 // The first character is required and must be in category `ALUND`.  All
 // subsequent characters are optional and must be in category `IDENT`:
 // ```
+// /// Return `true` if the specified `token` conforms to the requirements
+// /// of a C-style identifier, and `false` otherwise.
 // bool isIdentifier(const char *token)
-//     // Return 'true' if the specified 'token' conforms to the requirements
-//     // of a C-style identifier, and 'false' otherwise.
 // {
 //     assert(token);
 //
@@ -319,8 +319,8 @@ BSLS_IDENT("$Id: $")
 // BDE_VERIFY pragma: -FABC01
 
 namespace BloombergLP {
-
 namespace bdlb {
+
 /// This `struct` provides a namespace for a suite of pure procedures
 /// operating on the fundamental type `char`.
 struct CharType {

groups/bdl/bdlb/bdlb_hashutil.h

@@ -92,9 +92,9 @@ BSLS_IDENT("$Id: $")
 //   public:
 //     // CLASS METHODS
 //
-//     // Return a hash value calculated from the specified `object` using
-//     // the specified `size` as the number of slots.  The hash value
-//     // is guaranteed to be in the range [0, size).
+//     /// Return a hash value calculated from the specified `object` using
+//     /// the specified `size` as the number of slots.  The hash value
+//     /// is guaranteed to be in the range [0, size).
 //     static int hash(const UserDefinedTickerType& object, int size);
 //
 //     // Rest of the class definition omitted...
@@ -321,9 +321,9 @@ BSLS_IDENT("$Id: $")
 //
 //     // CREATORS
 //
-//     // Create a generator returning integers in a sequence starting at
-//     // the optionally specified `first` integer, with the optionally
-//     // specified `increment`.
+//     /// Create a generator returning integers in a sequence starting at
+//     /// the optionally specified `first` integer, with the optionally
+//     /// specified `increment`.
 //     explicit SequentialIntegers(int first = 1, int increment = 1)
 //         : d_current(first), d_inc(increment) {}
 //

groups/bdl/bdlc/bdlc_bitarray.h

@@ -131,14 +131,14 @@ BSLS_IDENT("$Id: $")
 //
 // First, we define the interface of `NullableVector`:
 // ```
+// /// This class implements a sequential container of elements of the
+// /// template parameter `TYPE`.
 // template <class TYPE>
 // class NullableVector {
-//     // This class implements a sequential container of elements of the
-//     // template parameter 'TYPE'.
 //
 //     // DATA
 //     bsl::vector<TYPE>  d_values;       // data elements
-//     bdlc::BitArray     d_nullFlags;    // 'true' indicates i'th element is
+//     bdlc::BitArray     d_nullFlags;    // `true` indicates i'th element is
 //                                        // null
 //
 //   private:
@@ -153,77 +153,80 @@ BSLS_IDENT("$Id: $")
 //
 //   public:
 //     // CREATORS
+//
+//     /// Construct a vector having the specified `initialLength` null
+//     /// elements.  Optionally specify a `basicAllocator` used to supply
+//     /// memory.  If `basicAllocator` is 0, the currently supplied
+//     /// default allocator is used.
 //     explicit
 //     NullableVector(bsl::size_t       initialLength,
 //                    bslma::Allocator *basicAllocator = 0);
-//         // Construct a vector having the specified 'initialLength' null
-//         // elements.  Optionally specify a 'basicAllocator' used to supply
-//         // memory.  If 'basicAllocator' is 0, the currently supplied
-//         // default allocator is used.
 //
 //     // ...
 //
 //     ~NullableVector();
 //         // Destroy this vector.
 //
 //     // MANIPULATORS
+//
+//     /// Append a null element to this vector.  Note that the appended
+//     /// element will have the same value as a default constructed `TYPE`
+//     /// object.
 //     void appendNullElement();
-//         // Append a null element to this vector.  Note that the appended
-//         // element will have the same value as a default constructed 'TYPE'
-//         // object.
 //
+//     /// Append an element having the specified `value` to the end of
+//     /// this vector.
 //     void appendElement(const TYPE& value);
-//         // Append an element having the specified 'value' to the end of
-//         // this vector.
 //
+//     /// Make the element at the specified `index` in this vector
+//     /// non-null.  The behavior is undefined unless `index < length()`.
 //     void makeNonNull(bsl::size_t index);
-//         // Make the element at the specified 'index' in this vector
-//         // non-null.  The behavior is undefined unless 'index < length()'.
 //
+//     /// Make the element at the specified `index` in this vector null.
+//     /// The behavior is undefined unless `index < length()`.  Note that
+//     /// the new value of the element will be the default constructed
+//     /// value for `TYPE`.
 //     void makeNull(bsl::size_t index);
-//         // Make the element at the specified 'index' in this vector null.
-//         // The behavior is undefined unless 'index < length()'.  Note that
-//         // the new value of the element will be the default constructed
-//         // value for 'TYPE'.
 //
+//     /// Return a reference providing modifiable access to the (valid)
+//     /// element at the specified `index` in this vector.  The behavior
+//     /// is undefined unless `index < length()`.  Note that if the
+//     /// element at `index` is null then the nullness flag is reset and
+//     /// the returned value is the default constructed value for `TYPE`.
 //     TYPE& modifiableElement(bsl::size_t index);
-//         // Return a reference providing modifiable access to the (valid)
-//         // element at the specified 'index' in this vector.  The behavior
-//         // is undefined unless 'index < length()'.  Note that if the
-//         // element at 'index' is null then the nullness flag is reset and
-//         // the returned value is the default constructed value for 'TYPE'.
 //
+//     /// Remove the element at the specified `index` in this vector.  The
+//     /// behavior is undefined unless `index < length()`.
 //     void removeElement(bsl::size_t index);
-//         // Remove the element at the specified 'index' in this vector.  The
-//         // behavior is undefined unless 'index < length()'.
 //
 //     // ACCESSORS
+//
+//     /// Return a reference providing non-modifiable access to the
+//     /// element at the specified `index` in this vector.  The behavior
+//     /// is undefined unless `index < length()`.  Note that if the
+//     /// element at `index` is null then the nullness flag is not reset
+//     /// and the returned value is the default constructed value for
+//     /// `TYPE`.
 //     const TYPE& constElement(bsl::size_t index) const;
-//         // Return a reference providing non-modifiable access to the
-//         // element at the specified 'index' in this vector.  The behavior
-//         // is undefined unless 'index < length()'.  Note that if the
-//         // element at 'index' is null then the nullness flag is not reset
-//         // and the returned value is the default constructed value for
-//         // 'TYPE'.
 //
+//     /// Return `true` if any element in this vector is non-null, and
+//     /// `false` otherwise.
 //     bool isAnyElementNonNull() const;
-//         // Return 'true' if any element in this vector is non-null, and
-//         // 'false' otherwise.
 //
+//     /// Return `true` if any element in this vector is null, and `false`
+//     /// otherwise.
 //     bool isAnyElementNull() const;
-//         // Return 'true' if any element in this vector is null, and 'false'
-//         // otherwise.
 //
+//     /// Return `true` if the element at the specified `index` in this
+//     /// vector is null, and `false` otherwise.  The behavior is
+//     /// undefined unless `index < length()`.
 //     bool isElementNull(bsl::size_t index) const;
-//         // Return 'true' if the element at the specified 'index' in this
-//         // vector is null, and 'false' otherwise.  The behavior is
-//         // undefined unless 'index < length()'.
 //
+//     /// Return the number of elements in this vector.
 //     bsl::size_t length() const;
-//         // Return the number of elements in this vector.
 //
+//     /// Return the number of null elements in this vector.
 //     bsl::size_t numNullElements() const;
-//         // Return the number of null elements in this vector.
 // };
 // ```
 // Then, we implement, in turn, each of the methods declared above: