Skip to content

Commit

Permalink
Cleanup documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
BDEBuild Role Account committed Oct 31, 2024
1 parent 6834793 commit 772cd51
Show file tree
Hide file tree
Showing 5 changed files with 216 additions and 214 deletions.
120 changes: 65 additions & 55 deletions groups/bdl/bdlat/bdlat_arrayfunctions.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <class MANIPULATOR>
// 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 <class ACCESSOR>
// 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:
//
Expand Down Expand Up @@ -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
Expand All @@ -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 <class MANIPULATOR>
// 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 <class ACCESSOR>
// 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.
Expand Down Expand Up @@ -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.
//
Expand Down Expand Up @@ -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<int> manipulator(index * 10);
Expand Down Expand Up @@ -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 <class ARRAY_TYPE>
// static int getElement(typename bdlat_ArrayFunctions
// ::ElementType<ARRAY_TYPE>::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<ARRAY_TYPE>::value);
//
Expand All @@ -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 <class ARRAY_TYPE>
// static int setElement(
// ARRAY_TYPE *object,
// int index,
// const typename bdlat_ArrayFunctions::ElementType<ARRAY_TYPE>
// ::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<ARRAY_TYPE>::value);
//
Expand Down Expand Up @@ -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<float>(index * 10);
Expand All @@ -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`.
Expand All @@ -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);
Expand Down Expand Up @@ -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<TYPE>`.
/// 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<TYPE>'.
// See the component-level documentation for more information.

// META-FUNCTIONS

Expand Down Expand Up @@ -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 <class TYPE, class ALLOC>
Expand Down
18 changes: 6 additions & 12 deletions groups/bdl/bdlat/bdlat_enumeratorinfo.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion groups/bdl/bdlat/bdlat_formattingmode.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
// ```
Expand Down
6 changes: 3 additions & 3 deletions groups/bdl/bdlat/bdlat_symbolicconverter.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
}

Expand All @@ -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
}

Expand Down
Loading

0 comments on commit 772cd51

Please sign in to comment.