From 6736a84580299eb05db9aba184283b73cb1f5201 Mon Sep 17 00:00:00 2001 From: Oleg Subbotin Date: Tue, 11 Feb 2025 13:07:00 -0500 Subject: [PATCH] Cleanup documentation --- groups/bdl/bdlb/bdlb_arrayutil.h | 1 + groups/bdl/bdlb/bdlb_chartype.h | 6 +- groups/bdl/bdlb/bdlb_hashutil.h | 12 +- groups/bdl/bdlc/bdlc_bitarray.h | 83 +++++++------ groups/bdl/bdlc/bdlc_compactedarray.h | 147 +++++++++++------------ groups/bdl/bdlc/bdlc_flathashmap.h | 12 +- groups/bdl/bdlc/bdlc_flathashmap_cpp03.h | 10 +- groups/bdl/bdlc/bdlc_flathashset.h | 31 +++-- groups/bdl/bdlc/bdlc_indexclerk.h | 40 +++--- groups/bdl/bdlc/bdlc_packedintarray.h | 26 ++-- 10 files changed, 187 insertions(+), 181 deletions(-) diff --git a/groups/bdl/bdlb/bdlb_arrayutil.h b/groups/bdl/bdlb/bdlb_arrayutil.h index 8c4d5725bf..acc92bb874 100644 --- a/groups/bdl/bdlb/bdlb_arrayutil.h +++ b/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) // { diff --git a/groups/bdl/bdlb/bdlb_chartype.h b/groups/bdl/bdlb/bdlb_chartype.h index ad63d70fc2..329cc06a7d 100644 --- a/groups/bdl/bdlb/bdlb_chartype.h +++ b/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 { diff --git a/groups/bdl/bdlb/bdlb_hashutil.h b/groups/bdl/bdlb/bdlb_hashutil.h index f13e0ab637..7421bc0d9d 100644 --- a/groups/bdl/bdlb/bdlb_hashutil.h +++ b/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) {} // diff --git a/groups/bdl/bdlc/bdlc_bitarray.h b/groups/bdl/bdlc/bdlc_bitarray.h index 2e693ff135..1990795317 100644 --- a/groups/bdl/bdlc/bdlc_bitarray.h +++ b/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 NullableVector { -// // This class implements a sequential container of elements of the -// // template parameter 'TYPE'. // // // DATA // bsl::vector 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,13 +153,14 @@ 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. // // // ... // @@ -167,63 +168,65 @@ BSLS_IDENT("$Id: $") // // 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: diff --git a/groups/bdl/bdlc/bdlc_compactedarray.h b/groups/bdl/bdlc/bdlc_compactedarray.h index 64e138d477..c2078fa7a1 100644 --- a/groups/bdl/bdlc/bdlc_compactedarray.h +++ b/groups/bdl/bdlc/bdlc_compactedarray.h @@ -57,20 +57,21 @@ BSLS_IDENT("$Id: $") // // public: // // CREATORS +// +// /// Create a `my_DailySchedule` object having the specified +// /// `initialLocationId`. Optionally specify a `basicAllocator` used +// /// to supply memory. If `basicAllocator` is 0, the currently +// /// installed default allocator is used. // my_DailySchedule(int initialLocationId, // bslma::Allocator *basicAllocator = 0); -// // Create a 'my_DailySchedule' object having the specified -// // 'initialLocationId'. Optionally specify a 'basicAllocator' used -// // to supply memory. If 'basicAllocator' is 0, the currently -// // installed default allocator is used. // // // ... // // }; // +// /// Return `true` if the specified `lhs` is lexicographically less than +// /// the specified `rhs` object, and `false` otherwise. // bool operator<(const my_DailySchedule& lhs, const my_DailySchedule& rhs); -// // Return 'true' if the specified 'lhs' is lexicographically less than -// // the specified 'rhs' object, and 'false' otherwise. // // // ---------------- // // my_DailySchedule @@ -242,9 +243,9 @@ class CompactedArray_RemoveAllProctor { // struct CompactedArray_CountedValue // ================================== -/// This `struct` represents a reference-counted value. Note that -/// comparison of `d_count` is intentionally omitted from the free -/// equality-comparison operators of this class. +/// This `struct` represents a reference-counted value. Note that comparison +/// of `d_count` is intentionally omitted from the free equality-comparison +/// operators of this class. template struct CompactedArray_CountedValue { @@ -254,18 +255,17 @@ struct CompactedArray_CountedValue { // CREATORS - /// Create a `CompactedArray_CountedValue` having the specified `value` - /// and reference `count`. The specified `basicAllocator` is used to - /// supply memory. The behavior is undefined unless - /// `0 != basicAllocator`. + /// Create a `CompactedArray_CountedValue` having the specified `value` and + /// reference `count`. The specified `basicAllocator` is used to supply + /// memory. The behavior is undefined unless `0 != basicAllocator`. CompactedArray_CountedValue(const TYPE& value, bsl::size_t count, bslma::Allocator *basicAllocator); /// Create a `CompactedArray_CountedValue` having the same underlying /// object value and reference count as the specified `original` object. - /// The specified `basicAllocator` is used to supply memory. The - /// behavior is undefined unless `0 != basicAllocator`. + /// The specified `basicAllocator` is used to supply memory. The behavior + /// is undefined unless `0 != basicAllocator`. CompactedArray_CountedValue( const CompactedArray_CountedValue& original, bslma::Allocator *basicAllocator); @@ -275,34 +275,32 @@ struct CompactedArray_CountedValue { // MANIPULATORS - /// Assign to this object the underlying object value and reference - /// count of the specified `rhs` object, and return a reference - /// providing modifiable access to this object. + /// Assign to this object the underlying object value and reference count + /// of the specified `rhs` object, and return a reference providing + /// modifiable access to this object. CompactedArray_CountedValue& operator=( const CompactedArray_CountedValue& rhs); }; // FREE OPERATORS -/// Return `true` if the underlying object value of the specified `lhs` is -/// the same as the underlying object value of the specified `rhs`, and -/// `false` otherwise. Note that the reference counts are intentionally -/// ignored. +/// Return `true` if the underlying object value of the specified `lhs` is the +/// same as the underlying object value of the specified `rhs`, and `false` +/// otherwise. Note that the reference counts are intentionally ignored. template bool operator==(const CompactedArray_CountedValue& lhs, const CompactedArray_CountedValue& rhs); -/// Return `true` if the underlying object value of the specified `lhs` is -/// not the same as the underlying object value of the specified `rhs`, and -/// `false` otherwise. Note that the reference counts are intentionally -/// ignored. +/// Return `true` if the underlying object value of the specified `lhs` is not +/// the same as the underlying object value of the specified `rhs`, and `false` +/// otherwise. Note that the reference counts are intentionally ignored. template bool operator!=(const CompactedArray_CountedValue& lhs, const CompactedArray_CountedValue& rhs); -/// Return `true` if the underlying object value of the specified `lhs` is -/// less than the value of the specified `rhs`, and `false` otherwise. Note -/// that the reference count is intentionally ignored. +/// Return `true` if the underlying object value of the specified `lhs` is less +/// than the value of the specified `rhs`, and `false` otherwise. Note that +/// the reference count is intentionally ignored. template bool operator<(const CompactedArray_CountedValue& lhs, const TYPE& rhs); @@ -318,9 +316,9 @@ bool operator<(const TYPE& lhs, const CompactedArray_CountedValue& rhs); /// This value-semantic class represents a random access iterator providing /// non-modifiable access to the elements of a `CompactedArray`. This class -/// provides all functionality of a random access iterator, as defined by -/// the standard, but is *not* compatible with most standard methods -/// requiring a bidirectional `const_iterator`. +/// provides all functionality of a random access iterator, as defined by the +/// standard, but is *not* compatible with most standard methods requiring a +/// bidirectional `const_iterator`. /// /// This class does not perform any bounds checking. Any iterator, `it`, /// referencing a `CompactedArray` `array`, remains valid while @@ -405,8 +403,8 @@ class CompactedArray_ConstIterator { /// Create a `CompactedArray_ConstIterator` object that refers to the /// element at the specified `index` in the specified `array`, or the - /// past-the-end iterator for `array` if `index == array->length()`. - /// The behavior is undefined unless `index <= array->length()`. + /// past-the-end iterator for `array` if `index == array->length()`. The + /// behavior is undefined unless `index <= array->length()`. CompactedArray_ConstIterator(const CompactedArray *array, bsl::size_t index); @@ -422,13 +420,13 @@ class CompactedArray_ConstIterator { /// specified `original` object. CompactedArray_ConstIterator(const CompactedArray_ConstIterator& original); + /// Destroy this object. //! ~CompactedArray_ConstIterator() = default; - // Destroy this object. // MANIPULATORS - /// Assign to this iterator the value of the specified `rhs` iterator, - /// and return a reference providing modifiable access to this iterator. + /// Assign to this iterator the value of the specified `rhs` iterator, and + /// return a reference providing modifiable access to this iterator. CompactedArray_ConstIterator& operator=( const CompactedArray_ConstIterator& rhs); @@ -640,13 +638,12 @@ class CompactedArray { /// undefined unless `index < uniqueLength()`. void erase(bsl::size_t index); - /// Find the element in `d_data` equal to the specified `value`, - /// increment the element's reference count by the specified `count`, - /// and return the element's index. If the `value` is not in `d_data`, - /// insert the element so as to retain sorted order in `d_data`, assign - /// `count` as the new element's reference count, and return the - /// inserted element's index. The behavior is undefined unless - /// `0 < count`. + /// Find the element in `d_data` equal to the specified `value`, increment + /// the element's reference count by the specified `count`, and return the + /// element's index. If the `value` is not in `d_data`, insert the element + /// so as to retain sorted order in `d_data`, assign `count` as the new + /// element's reference count, and return the inserted element's index. + /// The behavior is undefined unless `0 < count`. bsl::size_t increment(const TYPE& value, bsl::size_t count = 1); public: @@ -658,15 +655,15 @@ class CompactedArray { // CREATORS /// Create an empty `CompactedArray`. Optionally specify a - /// `basicAllocator` used to supply memory. If `basicAllocator` is 0, - /// the currently installed default allocator is used. + /// `basicAllocator` used to supply memory. If `basicAllocator` is 0, the + /// currently installed default allocator is used. explicit CompactedArray(bslma::Allocator *basicAllocator = 0); /// Create a `CompactedArray` having the specified `numElements`. /// Optionally specify a `value` to which each element will be set. If /// `value` is not specified, `TYPE()` is used. Optionally specify a - /// `basicAllocator` used to supply memory. If `basicAllocator` is 0, - /// the currently installed default allocator is used. + /// `basicAllocator` used to supply memory. If `basicAllocator` is 0, the + /// currently installed default allocator is used. explicit CompactedArray(bsl::size_t numElements, const TYPE& value = TYPE(), bslma::Allocator *basicAllocator = 0); @@ -683,8 +680,8 @@ class CompactedArray { // MANIPULATORS - /// Assign to this array the value of the specified `rhs` array, and - /// return a reference providing modifiable access to this array. + /// Assign to this array the value of the specified `rhs` array, and return + /// a reference providing modifiable access to this array. CompactedArray& operator=(const CompactedArray& rhs); /// Append to this array an element having the specified `value`. Note @@ -694,39 +691,39 @@ class CompactedArray { /// ``` void append(const TYPE& value); - /// Append to this array the elements from the specified `srcArray`. - /// Note that if this array and `srcArray` are the same, the behavior is - /// as if a copy of `srcArray` were passed. + /// Append to this array the elements from the specified `srcArray`. Note + /// that if this array and `srcArray` are the same, the behavior is as if a + /// copy of `srcArray` were passed. void append(const CompactedArray& srcArray); /// Append to this array the specified `numElements` starting at the /// specified `srcIndex` in the specified `srcArray`. The behavior is - /// undefined unless `srcIndex + numElements <= srcArray.length()`. - /// Note that if this array and `srcArray` are the same, the behavior is - /// as if a copy of `srcArray` were passed. + /// undefined unless `srcIndex + numElements <= srcArray.length()`. Note + /// that if this array and `srcArray` are the same, the behavior is as if a + /// copy of `srcArray` were passed. void append(const CompactedArray& srcArray, bsl::size_t srcIndex, bsl::size_t numElements); - /// Insert into this array, at the specified `dstIndex`, an element - /// having the specified `value`, shifting any elements originally at or - /// above `dstIndex` up by one index position. The behavior is - /// undefined unless `dstIndex <= length()`. + /// Insert into this array, at the specified `dstIndex`, an element having + /// the specified `value`, shifting any elements originally at or above + /// `dstIndex` up by one index position. The behavior is undefined unless + /// `dstIndex <= length()`. void insert(bsl::size_t dstIndex, const TYPE& value); - /// Insert into this array, at the specified `dst`, an element having - /// the specified `value`, shifting any elements originally at or above - /// `dst` up by one index position. Return an iterator to the newly - /// inserted element. The behavior is undefined unless `dst` is an - /// iterator over this array. + /// Insert into this array, at the specified `dst`, an element having the + /// specified `value`, shifting any elements originally at or above `dst` + /// up by one index position. Return an iterator to the newly inserted + /// element. The behavior is undefined unless `dst` is an iterator over + /// this array. const_iterator insert(const_iterator dst, const TYPE& value); - /// Insert into this array, at the specified `dstIndex`, the elements - /// from the specified `srcArray`, shifting any elements originally at - /// or above `dstIndex` up by `srcArray.length()` index positions. The - /// behavior is undefined unless `dstIndex <= length()`. Note that if - /// this array and `srcArray` are the same, the behavior is as if a copy - /// of `srcArray` were passed. + /// Insert into this array, at the specified `dstIndex`, the elements from + /// the specified `srcArray`, shifting any elements originally at or above + /// `dstIndex` up by `srcArray.length()` index positions. The behavior is + /// undefined unless `dstIndex <= length()`. Note that if this array and + /// `srcArray` are the same, the behavior is as if a copy of `srcArray` + /// were passed. void insert(bsl::size_t dstIndex, const CompactedArray& srcArray); /// Insert into this array, at the specified `dstIndex`, the specified @@ -750,10 +747,10 @@ class CompactedArray { /// Append to this array an element having the specified `value`. void push_back(const TYPE& value); - /// Remove from this array the element at the specified `dstIndex`. - /// Each element having an index greater than `dstIndex` before the - /// removal is shifted down by one index position. The behavior is - /// undefined unless `dstIndex < length()`. + /// Remove from this array the element at the specified `dstIndex`. Each + /// element having an index greater than `dstIndex` before the removal is + /// shifted down by one index position. The behavior is undefined unless + /// `dstIndex < length()`. void remove(bsl::size_t dstIndex); /// Remove from this array the specified `numElements` starting at the diff --git a/groups/bdl/bdlc/bdlc_flathashmap.h b/groups/bdl/bdlc/bdlc_flathashmap.h index d2c278f739..36a27a08b6 100644 --- a/groups/bdl/bdlc/bdlc_flathashmap.h +++ b/groups/bdl/bdlc/bdlc_flathashmap.h @@ -197,9 +197,9 @@ BSLS_IDENT("$Id: $") // entries, and determine the 10 most commonly used words in the given // documents: // ``` +// /// Assignable equivalent to 'WordTally::value_type'. Note that +// /// 'bsl::vector' requires assignable types. // typedef bsl::pair WordTallyEntry; -// // Assignable equivalent to 'WordTally::value_type'. Note that -// // 'bsl::vector' requires assignable types. // // struct WordTallyEntryCompare { // static bool lessThan(const WordTallyEntry& a, @@ -914,8 +914,8 @@ class FlatHashMap { /// inserted or updated entry. `obj` is left in a (valid) unspecified /// state. template - iterator insert_or_assign(const_iterator, - BloombergLP::bslmf::MovableRef key, + iterator insert_or_assign(const_iterator, + BloombergLP::bslmf::MovableRef key, MAPPED&& obj); /// If this map contains an entry with a key equivalent to the specified @@ -1789,11 +1789,11 @@ template template inline typename FlatHashMap::iterator -FlatHashMap::insert_or_assign(const_iterator, +FlatHashMap::insert_or_assign(const_iterator, const KEY& key, MAPPED&& obj) { - return insert_or_assign(key, + return insert_or_assign(key, BSLS_COMPILERFEATURES_FORWARD(MAPPED, obj)).first; } diff --git a/groups/bdl/bdlc/bdlc_flathashmap_cpp03.h b/groups/bdl/bdlc/bdlc_flathashmap_cpp03.h index 622a8f1f9b..c1adff4dc8 100644 --- a/groups/bdl/bdlc/bdlc_flathashmap_cpp03.h +++ b/groups/bdl/bdlc/bdlc_flathashmap_cpp03.h @@ -21,7 +21,7 @@ // regions of C++11 code, then this header contains no code and is not // '#include'd in the original header. // -// Generated on Tue Dec 17 08:14:39 2024 +// Generated on Tue Feb 11 13:05:49 2025 // Command line: sim_cpp11_features.pl bdlc_flathashmap.h #ifdef COMPILING_BDLC_FLATHASHMAP_H @@ -1094,8 +1094,8 @@ class FlatHashMap { BSLS_COMPILERFEATURES_FORWARD_REF(MAPPED) obj); template - iterator insert_or_assign(const_iterator, - BloombergLP::bslmf::MovableRef key, + iterator insert_or_assign(const_iterator, + BloombergLP::bslmf::MovableRef key, BSLS_COMPILERFEATURES_FORWARD_REF(MAPPED) obj); template @@ -4159,11 +4159,11 @@ template template inline typename FlatHashMap::iterator -FlatHashMap::insert_or_assign(const_iterator, +FlatHashMap::insert_or_assign(const_iterator, const KEY& key, BSLS_COMPILERFEATURES_FORWARD_REF(MAPPED) obj) { - return insert_or_assign(key, + return insert_or_assign(key, BSLS_COMPILERFEATURES_FORWARD(MAPPED, obj)).first; } diff --git a/groups/bdl/bdlc/bdlc_flathashset.h b/groups/bdl/bdlc/bdlc_flathashset.h index 6d247f2d65..2cb0991c0a 100644 --- a/groups/bdl/bdlc/bdlc_flathashset.h +++ b/groups/bdl/bdlc/bdlc_flathashset.h @@ -296,20 +296,23 @@ BSLS_IDENT("$Id: $") // class CustomerProfileHash { // public: // // CREATORS +// +// +// /// Create a `CustomerProfileHash` object. // //! CustomerProfileHash() = default; -// // Create a 'CustomerProfileHash' object. // +// /// Create a `CustomerProfileHash` object. Note that as +// /// `CustomerProfileHash` is an empty (stateless) type, this +// /// operation has no observable effect. // //! CustomerProfileHash(const CustomerProfileHash& original) = default; -// // Create a 'CustomerProfileHash' object. Note that as -// // 'CustomerProfileHash' is an empty (stateless) type, this -// // operation has no observable effect. // +// /// Destroy this object. // //! ~CustomerProfileHash() = default; -// // Destroy this object. // // // ACCESSORS +// +// /// Return a hash value for the specified `x`. // bsl::size_t operator()(const CustomerProfile& x) const; -// // Return a hash value for the specified 'x'. // }; // ``` // The hash function combines the several enumerated values from the class @@ -327,23 +330,25 @@ BSLS_IDENT("$Id: $") // class CustomerProfileEqual { // public: // // CREATORS +// +// /// Create a `CustomerProfileEqual` object. // //! CustomerProfileEqual() = default; -// // Create a 'CustomerProfileEqual' object. // +// /// Create a `CustomerProfileEqual` object. Note that as +// /// `CustomerProfileEqual` is an empty (stateless) type, this +// /// operation has no observable effect. // //! CustomerProfileEqual(const CustomerProfileEqual& original) // //! = default; -// // Create a 'CustomerProfileEqual' object. Note that as -// // 'CustomerProfileEqual' is an empty (stateless) type, this -// // operation has no observable effect. // +// /// Destroy this object. // //! ~CustomerProfileEqual() = default; -// // Destroy this object. // // // ACCESSORS +// +// /// Return `true` if the specified `lhs` has the same value as the +// /// specified `rhs`, and `false` otherwise. // bool operator()(const CustomerProfile& lhs, // const CustomerProfile& rhs) const; -// // Return 'true' if the specified 'lhs' has the same value as the -// // specified 'rhs', and 'false' otherwise. // }; // // // ACCESSORS diff --git a/groups/bdl/bdlc/bdlc_indexclerk.h b/groups/bdl/bdlc/bdlc_indexclerk.h index c8ef0e3eaf..38289b6fe6 100644 --- a/groups/bdl/bdlc/bdlc_indexclerk.h +++ b/groups/bdl/bdlc/bdlc_indexclerk.h @@ -68,13 +68,13 @@ BSLS_IDENT("$Id: $") // security values from a security array/clerk pair, you might write the // following two functions: // ``` +// /// Add a copy of the specified `newSecurity` to the specified +// /// `securityArray` at the index dispensed by the specified +// /// `securityClerk`. Also update the `securityClerk`, and return the id +// /// (in `securityArray`) for the newly added security. // int addSecurity(bsl::vector *securityArray, // bdlc::IndexClerk *securityClerk, // const Security& newSecurity) -// // Add a copy of the specified 'newSecurity' to the specified -// // 'securityArray' at the index dispensed by the specified -// // 'securityClerk'. Also update the 'securityClerk', and return the id -// // (in 'securityArray') for the newly added security. // { // BSLS_ASSERT(securityArray); // BSLS_ASSERT(securityClerk); @@ -91,14 +91,14 @@ BSLS_IDENT("$Id: $") // return id; // } // +// /// Remove the security object identified by the specified `securityId` +// /// from the specified `securityArray`, and update the specified +// /// `securityClerk` (making `securityId` available for reuse). The +// /// behavior is undefined unless `securityId` refers to an active +// /// security in `securityArray` dispensed by `securityClerk`. // void removeSecurity(bsl::vector *securityArray, // bdlc::IndexClerk *securityClerk, // int securityId) -// // Remove the security object identified by the specified 'securityId' -// // from the specified 'securityArray', and update the specified -// // 'securityClerk' (making 'securityId' available for reuse). The -// // behavior is undefined unless 'securityId' refers to an active -// // security in 'securityArray' dispensed by 'securityClerk'. // { // BSLS_ASSERT(securityArray); // BSLS_ASSERT(securityClerk); @@ -391,21 +391,21 @@ class IndexClerk { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` index clerks have the -/// same value, and `false` otherwise. Two `IndexClerk` objects have the -/// same value if they have the same `nextNewIndex()` and would always -/// generate the same sequence of integer indices. +/// Return `true` if the specified `lhs` and `rhs` index clerks have the same +/// value, and `false` otherwise. Two `IndexClerk` objects have the same value +/// if they have the same `nextNewIndex()` and would always generate the same +/// sequence of integer indices. bool operator==(const IndexClerk& lhs, const IndexClerk& rhs); -/// Return `true` if the specified `lhs` and `rhs` index clerks do not have -/// the same value, and `false` otherwise. Two `IndexClerk` objects do not -/// have the same value if they do not have the same `nextNewIndex()`, or -/// might generate different sequences of integer indices. +/// Return `true` if the specified `lhs` and `rhs` index clerks do not have the +/// same value, and `false` otherwise. Two `IndexClerk` objects do not have +/// the same value if they do not have the same `nextNewIndex()`, or might +/// generate different sequences of integer indices. bool operator!=(const IndexClerk& lhs, const IndexClerk& rhs); -/// Write the specified `rhs` index clerk to the specified output `stream` -/// in some single-line (human-readable) format, and return a reference to -/// the modifiable `stream`. +/// Write the specified `rhs` index clerk to the specified output `stream` in +/// some single-line (human-readable) format, and return a reference to the +/// modifiable `stream`. bsl::ostream& operator<<(bsl::ostream& stream, const IndexClerk& rhs); // ============================================================================ diff --git a/groups/bdl/bdlc/bdlc_packedintarray.h b/groups/bdl/bdlc/bdlc_packedintarray.h index eea7cf2000..bb8ea6cd91 100644 --- a/groups/bdl/bdlc/bdlc_packedintarray.h +++ b/groups/bdl/bdlc/bdlc_packedintarray.h @@ -55,8 +55,9 @@ BSLS_IDENT("$Id: $") // // ======= // // my_Date // // ======= +// +// /// A (value-semantic) attribute class that provides a very simple date. // class my_Date { -// // A (value-semantic) attribute class that provides a very simple date. // signed char d_day; // the day // signed char d_month; // the month // int d_year; // the year @@ -66,16 +67,17 @@ BSLS_IDENT("$Id: $") // // public: // // CREATORS +// +// /// Create a `my_Date` object having the optionally specified `day`, +// /// `month`, and `year`. Each, if unspecified, will default to 1. // explicit my_Date(int year = 1, // signed char month = 1, // signed char day = 1); -// // Create a 'my_Date' object having the optionally specified 'day', -// // 'month', and 'year'. Each, if unspecified, will default to 1. // }; // +// /// Return `true` if the specified `lhs` represents an earlier date than +// /// the specified `rhs` object, and `false` otherwise. // bool operator<(const my_Date& lhs, const my_Date& rhs); -// // Return 'true' if the specified 'lhs' represents an earlier date than -// // the specified 'rhs' object, and 'false' otherwise. // // // ------- // // my_Date @@ -353,11 +355,10 @@ struct PackedIntArrayImp_Unsigned { // ======================= /// This space-efficient value-semantic array class represents a sequence of -/// `STORAGE::EightByteStorageType` elements; -/// `STORAGE::EightByteStorageType` must be convertible to either a signed -/// or unsigned 64-bit integer using `static_cast`. The interface provides -/// functionality similar to a `vector` however references to -/// individual elements are not provided. +/// `STORAGE::EightByteStorageType` elements; `STORAGE::EightByteStorageType` +/// must be convertible to either a signed or unsigned 64-bit integer using +/// `static_cast`. The interface provides functionality similar to a +/// `vector` however references to individual elements are not provided. template class PackedIntArrayImp { @@ -687,9 +688,8 @@ class PackedIntArrayImp { // struct PackedIntArrayImpType // ============================ -/// This meta-function selects -/// `PackedIntArrayImp` if `TYPE` should be -/// stored as an unsigned integer, and +/// This meta-function selects `PackedIntArrayImp` +/// if `TYPE` should be stored as an unsigned integer, and /// `PackedIntArrayImp` otherwise. template struct PackedIntArrayImpType {