diff --git a/groups/bdl/bdlat/bdlat_arrayfunctions.h b/groups/bdl/bdlat/bdlat_arrayfunctions.h index af55b26c5a..6a643588fe 100644 --- a/groups/bdl/bdlat/bdlat_arrayfunctions.h +++ b/groups/bdl/bdlat/bdlat_arrayfunctions.h @@ -30,37 +30,40 @@ BSLS_IDENT("$Id: $") // of the type being plugged into the framework. // ``` // // MANIPULATORS +// +// /// Invoke the specified `manipulator` on the address of the element at +// /// the specified `index` of the specified `array`. Return the value +// /// from the invocation of `manipulator`. The behavior is undefined +// /// unless `0 <= index` and `index < bdlat_arraySize(*array)`. // template // int bdlat_arrayManipulateElement(YOUR_TYPE *array, // MANIPULATOR& manipulator, // int index); -// // Invoke the specified 'manipulator' on the address of the element at -// // the specified 'index' of the specified 'array'. Return the value -// // from the invocation of 'manipulator'. The behavior is undefined -// // unless '0 <= index' and 'index < bdlat_arraySize(*array)'. // +// /// Set the size of the specified modifiable `array` to the specified +// /// `newSize`. If `newSize > bdlat_arraySize(*array)`, then +// /// `newSize - bdlat_arraySize(*array)` elements with default values +// /// (i.e., `ElementType()`) are appended to `array`. If +// /// `newSize < bdlat_arraySize(*array)`, then the +// /// `bdlat_arraySize(*array) - newSize` elements at the end of `array` +// /// are destroyed. The behavior is undefined unless `0 <= newSize`. // void resize(YOUR_TYPE *array, int newSize); -// // Set the size of the specified modifiable 'array' to the specified -// // 'newSize'. If 'newSize > bdlat_arraySize(*array)', then -// // 'newSize - bdlat_arraySize(*array)' elements with default values -// // (i.e., 'ElementType()') are appended to 'array'. If -// // 'newSize < bdlat_arraySize(*array)', then the -// // 'bdlat_arraySize(*array) - newSize' elements at the end of 'array' -// // are destroyed. The behavior is undefined unless '0 <= newSize'. // // // ACCESSORS +// +// /// Invoke the specified `accessor` on a `const`-reference to the +// /// element at the specified `index` of the specified `array`. Return +// /// the value from the invocation of `accessor`. The behavior is +// /// undefined unless `0 <= index` and `index < bdlat_arraySize(array)`. // template // int bdlat_arrayAccessElement(const YOUR_TYPE& array, // ACCESSOR& accessor, // int index); -// // Invoke the specified 'accessor' on a 'const'-reference to the -// // element at the specified 'index' of the specified 'array'. Return -// // the value from the invocation of 'accessor'. The behavior is -// // undefined unless '0 <= index' and 'index < bdlat_arraySize(array)'. // +// /// Return the number of elements in the specified `array`. // bsl::size_t bdlat_arraySize(const YOUR_TYPE& array); -// // Return the number of elements in the specified 'array'. // ``` +// // The "array" type must also define two meta-functions in the // `bdlat_ArrayFunctions` namespace: // @@ -156,6 +159,7 @@ BSLS_IDENT("$Id: $") // } // close namespace mine // } // close enterprise namespace // ``` +// // We can now make `mine::MyIntArray` expose "array" behavior by implementing // the necessary `bdlat_ArrayFunctions` for `MyIntArray` inside the `mine` // namespace and defining the required meta-functions withing the @@ -168,40 +172,43 @@ BSLS_IDENT("$Id: $") // namespace mine { // // // MANIPULATORS +// +// /// Invoke the specified `manipulator` on the address of the element at +// /// the specified `index` of the specified `array`. Return the value +// /// from the invocation of `manipulator`. The behavior is undefined +// /// unless `0 <= index` and `index < bdlat_arraySize(*array)`. // template // int bdlat_arrayManipulateElement(MyIntArray *array, // MANIPULATOR& manipulator, // int index); -// // Invoke the specified 'manipulator' on the address of the element at -// // the specified 'index' of the specified 'array'. Return the value -// // from the invocation of 'manipulator'. The behavior is undefined -// // unless '0 <= index' and 'index < bdlat_arraySize(*array)'. // +// /// Set the size of the specified modifiable `array` to the specified +// /// `newSize`. If `newSize > bdlat_arraySize(*array)`, then +// /// `newSize - bdlat_arraySize(*array)` elements with default values +// /// (i.e., `ElementType()`) are appended to `array`. If +// /// `newSize < bdlat_arraySize(*array)`, then the +// /// `bdlat_arraySize(*array) - newSize` elements at the end of `array` +// /// are destroyed. The behavior is undefined unless `0 <= newSize`. // void bdlat_arrayResize(MyIntArray *array, int newSize); -// // Set the size of the specified modifiable 'array' to the specified -// // 'newSize'. If 'newSize > bdlat_arraySize(*array)', then -// // 'newSize - bdlat_arraySize(*array)' elements with default values -// // (i.e., 'ElementType()') are appended to 'array'. If -// // 'newSize < bdlat_arraySize(*array)', then the -// // 'bdlat_arraySize(*array) - newSize' elements at the end of 'array' -// // are destroyed. The behavior is undefined unless '0 <= newSize'. // // // ACCESSORS +// +// /// Invoke the specified `accessor` on a `const`-reference to the +// /// element at the specified `index` of the specified `array`. Return +// /// the value from the invocation of `accessor`. The behavior is +// /// undefined unless `0 <= index` and `index < bdlat_arraySize(array)`. // template // int bdlat_arrayAccessElement(const MyIntArray& array, // ACCESSOR& accessor, // int index); -// // Invoke the specified 'accessor' on a 'const'-reference to the -// // element at the specified 'index' of the specified 'array'. Return -// // the value from the invocation of 'accessor'. The behavior is -// // undefined unless '0 <= index' and 'index < bdlat_arraySize(array)'. // +// /// Return the number of elements in the specified `array`. // bsl::size_t bdlat_arraySize(const MyIntArray& array); -// // Return the number of elements in the specified 'array'. // // } // close namespace mine // } // close enterprise namespace // ``` +// // Then, we will implement these functions. Recall that the two (non-template) // functions should be defined in some `.cpp` file, unless you choose to make // them `inline` functions. @@ -270,6 +277,7 @@ BSLS_IDENT("$Id: $") // } // close namespace bdlat_ArrayFunctions // } // close enterprise namespace // ``` +// // This completes the `bdlat` infrastructure for `mine::MyIntArray` and // allows the generic software to recognize the type as an array abstraction. // @@ -366,7 +374,7 @@ BSLS_IDENT("$Id: $") // assert(0 == value) // } // -// // Set element 'index * 10' as its value; +// // Set element `index * 10` as its value; // // for (int index = 0; index < 4; ++index) { // SetElementManipulator manipulator(index * 10); @@ -401,18 +409,19 @@ BSLS_IDENT("$Id: $") // struct ArrayUtil { // // // CLASS METHODS +// +// /// Load to the specified `value` the element at the specified +// /// `index` of the specified `object` array. Return 0 if the +// /// element is successfully loaded to `value`, and a non-zero value +// /// otherwise. This function template requires that the specified +// /// `ARRAY_TYPE` is a `bdlat` "array" type. The behavior is +// /// undefined unless `0 <= index` and +// /// `index < bdlat_ArrayFunctions::size(object)`. // template // static int getElement(typename bdlat_ArrayFunctions // ::ElementType::Type *value, // const ARRAY_TYPE& object, // int index) -// // Load to the specified 'value' the element at the specified -// // 'index' of the specified 'object' array. Return 0 if the -// // element is successfully loaded to 'value', and a non-zero value -// // otherwise. This function template requires that the specified -// // 'ARRAY_TYPE' is a 'bdlat' "array" type. The behavior is -// // undefined unless '0 <= index' and -// // 'index < bdlat_ArrayFunctions::size(object)'. // { // BSLMF_ASSERT(bdlat_ArrayFunctions::IsArray::value); // @@ -426,19 +435,19 @@ BSLS_IDENT("$Id: $") // index); // } // +// /// Assign the specified `value` to the element of the specified +// /// `object` array at the specified `index`. Return 0 if the +// /// element is successfully assigned to `value`, and a non-zero +// /// value otherwise. This function template requires that the +// /// specified `ARRAY_TYPE` is a `bdlat` "array" type. The behavior +// /// is undefined unless `0 <= index` and +// /// `index < bdlat_ArrayFunctions::size(*object)`. // template // static int setElement( // ARRAY_TYPE *object, // int index, // const typename bdlat_ArrayFunctions::ElementType // ::Type& value) -// // Assign the specified 'value' to the element of the specified -// // 'object' array at the specified 'index'. Return 0 if the -// // element is successfully assigned to 'value', and a non-zero -// // value otherwise. This function template requires that the -// // specified 'ARRAY_TYPE' is a 'bdlat' "array" type. The behavior -// // is undefined unless '0 <= index' and -// // 'index < bdlat_ArrayFunctions::size(*object)'. // { // BSLMF_ASSERT(bdlat_ArrayFunctions::IsArray::value); // @@ -572,7 +581,7 @@ BSLS_IDENT("$Id: $") // assert(0.0 == value); // } // -// // Set element 'index * 10' as its value; +// // Set element `index * 10` as its value; // // for (int index = 0; index < 4; ++index) { // float value = static_cast(index * 10); @@ -590,6 +599,7 @@ BSLS_IDENT("$Id: $") // } // } // ``` +// // Notice that syntax and order of `bdlat_ArrayFunctions` function // calls have not been changed. The only difference is that the element // type has changed from `int` to `float`. @@ -615,7 +625,7 @@ BSLS_IDENT("$Id: $") // assert("" == value); // } // -// // Set element 'index * 10' as its value; +// // Set element `index * 10` as its value; // // for (int index = 0; index < 4; ++index) { // bsl::ostringstream oss; oss << (index * 10); @@ -653,10 +663,10 @@ namespace BloombergLP { // namespace bdlat_ArrayFunctions // ============================== +/// This `namespace` provides functions that expose "array" behavior for +/// "array" types. Specializations are provided for `bsl::vector`. +/// See the component-level documentation for more information. namespace bdlat_ArrayFunctions { - // This 'namespace' provides functions that expose "array" behavior for - // "array" types. Specializations are provided for 'bsl::vector'. - // See the component-level documentation for more information. // META-FUNCTIONS @@ -713,10 +723,10 @@ namespace bdlat_ArrayFunctions { // bsl::vector declarations // ======================== +/// This namespace declaration adds the implementation of the "array" traits +/// for `bsl::vector` to `bdlat_ArrayFunctions`. Note that `bsl::vector` is +/// the canonical "array" type. namespace bdlat_ArrayFunctions { - // This namespace declaration adds the implementation of the "array" traits - // for 'bsl::vector' to 'bdlat_ArrayFunctions'. Note that 'bsl::vector' is - // the canonical "array" type. // META-FUNCTIONS template diff --git a/groups/bdl/bdlat/bdlat_enumeratorinfo.h b/groups/bdl/bdlat/bdlat_enumeratorinfo.h index 3f371fb7a7..b55b93cc3b 100644 --- a/groups/bdl/bdlat/bdlat_enumeratorinfo.h +++ b/groups/bdl/bdlat/bdlat_enumeratorinfo.h @@ -71,21 +71,15 @@ struct bdlat_EnumeratorInfo { // CREATORS - // The following methods are not defined by design: - //.. - // bdlat_EnumeratorInfo(); - // bdlat_EnumeratorInfo(const bdlat_EnumeratorInfo& original); - // ~bdlat_EnumeratorInfo(); - //.. - // The corresponding methods supplied by the compiler are sufficient. + /// Compiler-generated methods. + //! bdlat_EnumeratorInfo() = default; + //! bdlat_EnumeratorInfo(const bdlat_EnumeratorInfo& original) = default; + //! ~bdlat_EnumeratorInfo() = default; // MANIPULATORS - // The following method is not defined by design: - //.. - // bdlat_EnumeratorInfo& operator=(const bdlat_EnumeratorInfo& rhs); - //.. - // The assignment operator supplied by the compiler is sufficient. + /// Compiler-generated methods. + //! bdlat_EnumeratorInfo& operator=(const bdlat_EnumeratorInfo& rhs); /// Return a reference to the modifiable annotation of this enumerator /// info object. diff --git a/groups/bdl/bdlat/bdlat_formattingmode.h b/groups/bdl/bdlat/bdlat_formattingmode.h index 46f1e72733..322b46c9d9 100644 --- a/groups/bdl/bdlat/bdlat_formattingmode.h +++ b/groups/bdl/bdlat/bdlat_formattingmode.h @@ -42,7 +42,7 @@ BSLS_IDENT("$Id: $") // e_ATTRIBUTE Use attribute formatting (for XSD attributes). // e_SIMPLE_CONTENT Use simple content formatting (for XSD simple // content types). -// e_NILLABLE Use nillable formatting (for XSD 'nillable' +// e_NILLABLE Use nillable formatting (for XSD `nillable` // option). // e_LIST Use the list format (this is used for arrays). // ``` diff --git a/groups/bdl/bdlat/bdlat_symbolicconverter.h b/groups/bdl/bdlat/bdlat_symbolicconverter.h index 9fb18a3808..bfb2e91e0d 100644 --- a/groups/bdl/bdlat/bdlat_symbolicconverter.h +++ b/groups/bdl/bdlat/bdlat_symbolicconverter.h @@ -128,7 +128,7 @@ BSLS_IDENT("$Id: $") // assignment operator from the // destination to the source. This is // determined using -// 'bslmf_isconvertible'. +// `bslmf_isconvertible`. // ``` // Any other combination of destination and source categories will fail to // convert. @@ -840,7 +840,7 @@ int bdlat_SymbolicConverter_Imp::convert( enum { k_SUCCESS = 0 }; if (bdlat_NullableValueFunctions::isNull(rhs)) { - // ignore the value and let '*lhs' contain its *default* value + // ignore the value and let `*lhs` contain its *default* value return k_SUCCESS; // RETURN } @@ -859,7 +859,7 @@ int bdlat_SymbolicConverter_Imp::convert( enum { k_SUCCESS = 0 }; if (bdlat_NullableValueFunctions::isNull(rhs)) { - // ignore the value and let '*lhs' contain its *default* value + // ignore the value and let `*lhs` contain its *default* value return k_SUCCESS; // RETURN } diff --git a/groups/bdl/bdlat/bdlat_typecategory.h b/groups/bdl/bdlat/bdlat_typecategory.h index f1e1a78ebc..085afcf607 100644 --- a/groups/bdl/bdlat/bdlat_typecategory.h +++ b/groups/bdl/bdlat/bdlat_typecategory.h @@ -49,24 +49,24 @@ BSLS_IDENT("$Id: $") // Category Tag Assigned To // ------------ ----------- // Array types that expose "array" behavior through the -// 'bdlat_ArrayFunctions' 'namespace'. +// `bdlat_ArrayFunctions` `namespace`. // // Choice types that expose "choice" behavior through the -// 'bdlat_ChoiceFunctions' 'namespace'. +// `bdlat_ChoiceFunctions` `namespace`. // // CustomizedType types that expose "customized type" behavior through the -// 'bdlat_CustomizedTypeFunctions' 'namespace'. +// `bdlat_CustomizedTypeFunctions` `namespace`. // // DynamicType types that can select a category at runtime // // Enumeration types that expose "enumeration" behavior through the -// 'bdlat_EnumFunctions' 'namespace'. +// `bdlat_EnumFunctions` `namespace`. // // NullableValue types that expose "nullable" behavior through the -// 'bdlat_NullableValueFunctions' 'namespace'. +// `bdlat_NullableValueFunctions` `namespace`. // // Sequence types that expose "sequence" behavior through the -// 'bdlat_SequenceFunctions' 'namespace'. +// `bdlat_SequenceFunctions` `namespace`. // // Simple all other types (i.e., scalars) // ``` @@ -122,6 +122,10 @@ BSLS_IDENT("$Id: $") // A `MANIPULATOR` functor must be invocable by one or more of these seven // overloads: // ``` +// /// Modify the specified `object` that matches the specified `category`. +// /// Return 0 on success and a non-zero value otherwise. On failure, +// /// `object` is left in a valid but unspecified state. The behavior is +// /// undefined unless the type category of `object` matches `category`. // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::Array category); // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::Choice category); // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::CustomizedType category); @@ -129,10 +133,6 @@ BSLS_IDENT("$Id: $") // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::NullableValue category); // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::Sequence category); // int MANIPULATOR(TYPE *object, bdlat_TypeCategory::Simple category); -// // Modify the specified 'object' that matches the specified 'category'. -// // Return 0 on success and a non-zero value otherwise. On failure, -// // 'object' is left in a valid but unspecified state. The behavior is -// // undefined unless the type category of 'object' matches 'category'. // ``` // Notice that, potentially, one can have an overload for each of the "static" // `bdlat` type categories (i.e., all except for the "dynamic" category). @@ -140,14 +140,13 @@ BSLS_IDENT("$Id: $") // Additionally, the functor *must* provide an overload for `bslmf::Nil` // (required for compilation): // ``` -// -// int MANIPULATOR(TYPE *object, bslmf::Nil); -// // Modify the specified 'object'. Return 0 on success and a non-zero -// // value otherwise. On failure, 'object' is left in a valid but -// // unspecified state. The behavior is undefined if 'TYPE' is 'bdlat' -// // compatible (i.e., belongs in one or more of the seven 'bdlat' -// // categories). Note that 'bdlat' compatible types are expected to be -// // dispatched to one of the seven overloads declared above. +// /// Modify the specified `object`. Return 0 on success and a non-zero +// /// value otherwise. On failure, `object` is left in a valid but +// /// unspecified state. The behavior is undefined if `TYPE` is `bdlat` +// /// compatible (i.e., belongs in one or more of the seven `bdlat` +// /// categories). Note that `bdlat` compatible types are expected to be +// /// dispatched to one of the seven overloads declared above. +// int MANIPULATOR(TYPE *object, bslmf::Nil); // ``` // Typically, the "Nil" overload returns an error code (or even aborts). // @@ -155,6 +154,11 @@ BSLS_IDENT("$Id: $") ///- - - - - - - - - - // A `ACCESSOR` functor must invocable by one or more of these seven overloads: // ``` +// /// Access the specified `object` that matches the specified `cat` +// /// (category). Return 0 on success and a non-zero value otherwise. +// /// The behavior is undefined unless the type category of `object` +// /// matches `cat` (category). Note that, in typical use, invocation of +// /// this functor object changes its state based on the state of `object`. // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::Array cat); // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::Choice cat); // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::CustomizedType cat); @@ -162,12 +166,6 @@ BSLS_IDENT("$Id: $") // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::NullableValue cat); // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::Sequence cat); // int ACCESSOR(const TYPE& object, bdlat_TypeCategory::Simple cat); -// // Access the specified 'object' that matches the specified 'cat' -// // (category). Return 0 on success and a non-zero value otherwise. -// // The behavior is undefined unless the type category of 'object' -// // matches 'cat' (category). Note that, in typical use, invocation of -// // this functor object changes its state based on the state of -// // 'object'. // ``` // Notice that, potentially, one can have an overload for each of the "static" // `bdlat` type categories (i.e., all except for the "dyanamic" category). @@ -175,12 +173,12 @@ BSLS_IDENT("$Id: $") // Additionally, the functor *must* provide an overload for `bslmf::Nil` // (required for compilation): // ``` +// /// Access the specified `object`. Return 0 on success and a non-zero +// /// value otherwise. The behavior is undefined if `TYPE` is `bdlat` +// /// compatible (i.e., belongs in one or more of the seven `bdlat` +// /// categories). Note that `bdlat` compatible types are expected to be +// /// dispatched to one of the seven overloads declared above. // int ACCESSOR(const TYPE& object, bslmf::Nil); -// // Access the specified 'object'. Return 0 on success and a non-zero -// // value otherwise. The behavior is undefined if 'TYPE' is 'bdlat' -// // compatible (i.e., belongs in one or more of the seven 'bdlat' -// // categories). Note that 'bdlat' compatible types are expected to be -// // dispatched to one of the seven overloads declared above. // ``` // Typically, the "Nil" overload returns an error code (or even aborts). // @@ -201,8 +199,8 @@ BSLS_IDENT("$Id: $") // These function templates provide a uniform interface for operations on a // wide variety of types. The details of what occurs in each "manipulate" or // "access" action depends on a user-provided functor object. See -// {`MANIPULATOR` Functors} and {`ACCESSOR` Functors} for the requirements on -// those functors. +// [](#`MANIPULATOR` Functors) and [](#`ACCESSOR` Functors) for the +// requirements on those functors. // // For a user-defined type to operate in the type category framework, that type // must define in the namespace in which it is defined, all required overloads @@ -228,149 +226,151 @@ BSLS_IDENT("$Id: $") // be replaced with the name of the type being plugged into the framework. // ``` // // MANIPULATORS +// +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Array` +// /// tag object (2nd argument). If `object` is not a `bdlat` "array" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`MANIPULATOR` Functors) for the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateArray(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Array' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "array" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'MANIPULATOR' Functors} for the requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Choice` +// /// tag object (2nd argument). If `object` is not a `bdlat` "choice" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`MANIPULATOR` Functors) for the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateChoice(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Choice' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "choice" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'MANIPULATOR' Functors} for the requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::CustomizedType` tag object (2nd argument). If +// /// `object` is not a `bdlat` "customized type" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`MANIPULATOR` Functors) +// /// for the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateCustomizedType(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::CustomizedType' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "customized type" type, pass a -// // 'bslmf::Nil' tag object as the second argument. See {'MANIPULATOR' -// // Functors} for the requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::Enumeration` tag object (2nd argument). If +// /// `object` is not a `bdlat` "enumeration" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`MANIPULATOR` Functors) for +// /// the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateEnumeration(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::Enumeration' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "enumeration" type, pass a 'bslmf::Nil' -// // tag object as the second argument. See {'MANIPULATOR' Functors} for -// // the requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::NullableValue` tag object (2nd argument). If +// /// `object` is not a `bdlat` "nullable value" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`MANIPULATOR` Functors) for +// /// the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateNullableValue(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::NullableValue' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "nullable value" type, pass a 'bslmf::Nil' -// // tag object as the second argument. See {'MANIPULATOR' Functors} for -// // the requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::Sequence` tag object (2nd argument). If +// /// `object` is not a `bdlat` "sequence" type, pass a `bslmf::Nil` tag +// /// object as the second argument. See [](#`MANIPULATOR` Functors) for the +// /// requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateSequence(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::Sequence' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "sequence" type, pass a 'bslmf::Nil' tag -// // object as the second argument. See {'MANIPULATOR' Functors} for the -// // requirements on 'manipulator'. // +// /// Return the result of invoking the specified `manipulator` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Simple` +// /// tag object (2nd argument). If `object` is not a `bdlat` "simple" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`MANIPULATOR` Functors) for the requirements on `manipulator`. // template // int bdlat_typeCategoryManipulateSimple(YOUR_TYPE *object, // MANIPULATOR& manipulator); -// // Return the result of invoking the specified 'manipulator' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Simple' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "simple" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'MANIPULATOR' Functors} for the requirements on 'manipulator'. // // // ACCESSORS +// +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Array` +// /// tag object (2nd argument). If `object` is not a `bdlat` "array" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`ACCESSOR` Functors) for the requirements on `accessor`. // template // int bdlat_typeCategoryAccessArray(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Array' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "array" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'ACCESSOR' Functors} for the requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Choice` +// /// tag object (2nd argument). If `object` is not a `bdlat` "choice" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`ACCESSOR` Functors) for the requirements on `accessor`. // template // int bdlat_typeCategoryAccessChoice(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Choice' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "choice" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'ACCESSOR' Functors} for the requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::CustomizedType` tag object (2nd argument). If +// /// `object` is not a `bdlat` "customized type" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`ACCESSOR` Functors) for +// /// the requirements on `accessor`. // template // int bdlat_typeCategoryAccessCustomizedType(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::CustomizedType' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "customized type" type, pass a -// // 'bslmf::Nil' tag object as the second argument. See {'ACCESSOR' -// // Functors} for the requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::Enumeration` tag object (2nd argument). If +// /// `object` is not a `bdlat` "enumeration type" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`ACCESSOR` Functors) for +// /// the requirements on `accessor`. // template // int bdlat_typeCategoryAccessEnumeration(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::Enumeration' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "enumeration type" type, pass a -// // 'bslmf::Nil' tag object as the second argument. See {'ACCESSOR' -// // Functors} for the requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::NullableValue` tag object (2nd argument). If +// /// `object` is not a `bdlat` "nullable value" type, pass a `bslmf::Nil` +// /// tag object as the second argument. See [](#`ACCESSOR` Functors) for +// /// the requirements on `accessor`. // template // int bdlat_typeCategoryAccessNullableValue(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::NullableValue' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "nullable value" type, pass a 'bslmf::Nil' -// // tag object as the second argument. See {'ACCESSOR' Functors} for -// // the requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a +// /// `bdlat_TypeCategory::Sequence` tag object (2nd argument). If +// /// `object` is not a `bdlat` "sequence" type, pass a `bslmf::Nil` tag +// /// object as the second argument. See [](#`ACCESSOR` Functors) for the +// /// requirements on `accessor`. // template // int bdlat_typeCategoryAccessSequence(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a -// // 'bdlat_TypeCategory::Sequence' tag object (2nd argument). If -// // 'object' is not a 'bdlat' "sequence" type, pass a 'bslmf::Nil' tag -// // object as the second argument. See {'ACCESSOR' Functors} for the -// // requirements on 'accessor'. // +// /// Return the result of invoking the specified `accessor` with the +// /// specified `object` (1st argument) and a `bdlat_TypeCategory::Simple` +// /// tag object (2nd argument). If `object` is not a `bdlat` "simple" +// /// type, pass a `bslmf::Nil` tag object as the second argument. See +// /// [](#`ACCESSOR` Functors) for the requirements on `accessor`. // template // int bdlat_typeCategoryAccessSimple(const YOUR_TYPE& object, // ACCESSOR& accessor); -// // Return the result of invoking the specified 'accessor' with the -// // specified 'object' (1st argument) and a 'bdlat_TypeCategory::Simple' -// // tag object (2nd argument). If 'object' is not a 'bdlat' "simple" -// // type, pass a 'bslmf::Nil' tag object as the second argument. See -// // {'ACCESSOR' Functors} for the requirements on 'accessor'. // +// /// Return the *runtime* type category for the specified `object`. The +// /// behavior is undefined if `bdlat_TypeCategory::e_DYNAMIC_CATEGORY` is +// /// returned. Note that the compile time analog to this function +// /// (template) is `bdlat_TypeCategory::Select`, a meta-function that +// /// defines a type corresponding to the category tag class of +// /// `YOUR_TYPE`. // bdlat_TypeCategory::Value bdlat_typeCategorySelect( // const YOUR_TYPE& object); -// // Return the *runtime* type category for the specified 'object'. The -// // behavior is undefined if 'bdlat_TypeCategory::e_DYNAMIC_CATEGORY' is -// // returned. Note that the compile time analog to this function -// // (template) is 'bdlat_TypeCategory::Select', a meta-function that -// // defines a type corresponding to the category tag class of -// // 'YOUR_TYPE'. // ``` // ///Dynamic Types @@ -439,10 +439,10 @@ BSLS_IDENT("$Id: $") // namespace BloombergLP { // namespace mine { // +// /// Print the category of the specified `object` followed by the value +// /// of `object` to the specified output `stream`. // template // void printCategoryAndValue(bsl::ostream& stream, const TYPE& object); -// // Print the category of the specified 'object' followed by the value -// // of 'object' to the specified output 'stream'. // ``` // Then, to implement this function, we will use a set of helper functions that // are overloaded based on the category tag. The first set of helper functions @@ -515,22 +515,21 @@ BSLS_IDENT("$Id: $") // Now, we can implement the `printCategoryAndValue` function in terms of the // `printCategory` and `printValue` helper functions: // ``` +// template +// void printCategoryAndValue(bsl::ostream& stream, const TYPE& object) +// { +// typedef typename +// bdlat_TypeCategory::Select::Type TypeCategory; // -// template -// void printCategoryAndValue(bsl::ostream& stream, const TYPE& object) -// { -// typedef typename -// bdlat_TypeCategory::Select::Type TypeCategory; -// -// printCategory(stream, TypeCategory()); +// printCategory(stream, TypeCategory()); // -// stream << ": "; +// stream << ": "; // -// printValue(stream, object, TypeCategory()); -// } +// printValue(stream, object, TypeCategory()); +// } // -// } // close package namespace -// } // close enterprise namespace +// } // close package namespace +// } // close enterprise namespace // ``` // Finally, we can exercise the `printCategoryAndValue` function on objects // that fall in different (non-dynamic) type categories. @@ -715,9 +714,9 @@ BSLS_IDENT("$Id: $") // namespace BloombergLP { // namespace mine { // +// /// This class can represent data in two forms: either a `bsl::string` +// /// or as a `bsl::vector` of `char` values. // class MyDynamicType { -// // This class can represent data in two forms: either a 'bsl::string' -// // or as a 'bsl::vector' of 'char' values. // // // PRIVATE DATA MEMBERS // bsl::vector d_vectorChar; // Note: Production code should use a @@ -785,7 +784,7 @@ BSLS_IDENT("$Id: $") // // assert(0 == "Reached"); // -// // Note that this 'return' is never reached and hence the returned +// // Note that this `return` is never reached and hence the returned // // value is immaterial. // // return bdlat_TypeCategory::e_SIMPLE_CATEGORY; @@ -1093,10 +1092,10 @@ struct bdlat_TypeCategoryUtil { /// * `bdlat_TypeCategoryFunctions::manipulateSimple` /// /// where each function is invoked with the specified `object` and - /// `manipulator`. See {`MANIPULATOR` Functors} for the requirements on - /// `manipulator`. Return the value returned by the invoked function. - /// The behavior is undefined unless the parameterized `TYPE` supports - /// the type category returned by the call to the + /// `manipulator`. See [](#`MANIPULATOR` Functors) for the requirements + /// on `manipulator`. Return the value returned by the invoked function. + /// The behavior is undefined unless the parameterized `TYPE` supports the + /// type category returned by the call to the /// `bdlat_TypeCategoryFunctions::select` function. template static int manipulateByCategory(TYPE *object, @@ -1114,7 +1113,7 @@ struct bdlat_TypeCategoryUtil { /// * `bdlat_TypeCategoryFunctions::accessSimple` /// /// where each function is invoked with the specified `object` and - /// `accessor`. See {`ACCESSOR` Functors} for the requirements on + /// `accessor`. See [](#`ACCESSOR` Functors) for the requirements on /// `accessor`. Return the value returned by the invoked function. The /// behavior is undefined unless the parameterized `TYPE` supports the /// type category returned by the call to the @@ -1128,12 +1127,11 @@ struct bdlat_TypeCategoryUtil { // namespace bdlat_TypeCategoryFunctions // ===================================== +/// This namespace contains function templates pertaining to type categories. +/// For each of the seven `bdlat` type categories there are two function +/// templates: "maniuplate*Type*" and "access*Type". Additionally, the `select` +/// function template returns the type (an enumerator) for a given object. namespace bdlat_TypeCategoryFunctions { - // This namespace contains function templates pertaining to type - // categories. For each of the seven 'bdlat' type categories there are two - // function templates: "maniuplate*Type*" and "access*Type". Additionally, - // the 'select' function template returns the type (an enumerator) for a - // given object. // MANIPULATORS @@ -1272,7 +1270,7 @@ namespace bdlat_TypeCategoryFunctions { // The following functions should be overloaded for other types (in their // respective namespaces). The following functions are the default - // implementations (for 'bas_codegen.pl'-generated types). Do *not* call + // implementations (for `bas_codegen.pl`-generated types). Do *not* call // these functions directly. Use the functions above instead. // MANIPULATORS