diff --git a/groups/bal/balb/balb_filecleanerconfiguration.h b/groups/bal/balb/balb_filecleanerconfiguration.h index 3d9c2fae0e..85d68409f1 100644 --- a/groups/bal/balb/balb_filecleanerconfiguration.h +++ b/groups/bal/balb/balb_filecleanerconfiguration.h @@ -100,8 +100,7 @@ namespace balb { // ============================== /// This simply constrained (value-semantic) attribute class characterizes -/// configuration parameters for a file cleaner. See the {Attributes} -/// section under @DESCRIPTION in the component-level documentation for +/// configuration parameters for a file cleaner. See the [](#Attributes) for /// information on the class attributes. Note that the class invariants are /// identically the constraints on the individual attributes. /// @@ -135,37 +134,36 @@ class FileCleanerConfiguration { // CREATORS /// Create a file cleaner configuration object having default values for - /// all attributes. Optionally specify a `basicAllocator` used to - /// supply memory. If `basicAllocator` is 0, the currently installed - /// default allocator is used. + /// all attributes. Optionally specify a `basicAllocator` used to supply + /// memory. If `basicAllocator` is 0, the currently installed default + /// allocator is used. explicit FileCleanerConfiguration(bslma::Allocator *basicAllocator = 0); /// Create a file cleaner configuration object having the specified - /// `filePattern`, `maxAge`, and `minNumber` attribute values. - /// Optionally specify a `basicAllocator` used to supply memory. If - /// `basicAllocator` is 0, the currently installed default allocator is - /// used. + /// `filePattern`, `maxAge`, and `minNumber` attribute values. Optionally + /// specify a `basicAllocator` used to supply memory. If `basicAllocator` + /// is 0, the currently installed default allocator is used. FileCleanerConfiguration(const bsl::string_view& filePattern, const bsls::TimeInterval& maxAge, int minNumber, bslma::Allocator *basicAllocator = 0); - /// Create a file cleaner configuration object having the in-core value - /// of the specified `original` object. Optionally specify a - /// `basicAllocator` used to supply memory. If `basicAllocator` is 0, - /// the currently installed default allocator is used. + /// Create a file cleaner configuration object having the in-core value of + /// the specified `original` object. Optionally specify a `basicAllocator` + /// used to supply memory. If `basicAllocator` is 0, the currently + /// installed default allocator is used. FileCleanerConfiguration( const FileCleanerConfiguration& original, bslma::Allocator *basicAllocator = 0); + /// Destroy this object. //! ~FileCleanerConfiguration() = default; - // Destroy this object. // MANIPULATORS - /// Assign to this file cleaner configuration object the in-core value - /// of the specified `rhs` object, and return a reference providing - /// modifiable access to this object. + /// Assign to this file cleaner configuration object the in-core value of + /// the specified `rhs` object, and return a reference providing modifiable + /// access to this object. FileCleanerConfiguration& operator=(const FileCleanerConfiguration& rhs); /// Set the file pattern attribute of this object to the specified @@ -176,8 +174,8 @@ class FileCleanerConfiguration { /// `maxAge`. void setMaxFileAge(const bsls::TimeInterval& maxAge); - /// Set the minimum number of files to keep attribute of this object to - /// the specified `minNumber`. + /// Set the minimum number of files to keep attribute of this object to the + /// specified `minNumber`. void setMinNumFiles(int minNumber); // ACCESSORS @@ -208,10 +206,10 @@ class FileCleanerConfiguration { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` attribute objects have -/// the same (in-core) value, and `false` otherwise. Two attribute objects -/// have the same in-core value if each respective attribute has the same -/// in-core value. +/// Return `true` if the specified `lhs` and `rhs` attribute objects have the +/// same (in-core) value, and `false` otherwise. Two attribute objects have +/// the same in-core value if each respective attribute has the same in-core +/// value. bool operator==(const FileCleanerConfiguration& lhs, const FileCleanerConfiguration& rhs); @@ -222,9 +220,8 @@ bool operator==(const FileCleanerConfiguration& lhs, bool operator!=(const FileCleanerConfiguration& lhs, const FileCleanerConfiguration& rhs); -/// Write a reasonable representation of the specified `configuration` -/// object to the specified output `stream`, and return a reference to -/// `stream`. +/// Write a reasonable representation of the specified `configuration` object +/// to the specified output `stream`, and return a reference to `stream`. bsl::ostream& operator<<(bsl::ostream& stream, const FileCleanerConfiguration& configuration); diff --git a/groups/bal/balber/balber_beruniversaltagnumber.h b/groups/bal/balber/balber_beruniversaltagnumber.h index ba141e6d97..4cb1da6793 100644 --- a/groups/bal/balber/balber_beruniversaltagnumber.h +++ b/groups/bal/balber/balber_beruniversaltagnumber.h @@ -218,7 +218,7 @@ struct BerUniversalTagNumber { /// `alternateTag` any alternative tag numbers corresponding to /// `object`. The behavior is undefined if the type category of /// `object` and the `formattingMode` does not permit a universal tag - /// number (see {DESCRIPTION} for allowed type categories and formatting + /// number (see [](#DESCRIPTION) for allowed type categories and formatting /// modes). Note that if an alternate tag number does not exist for /// `object` then `alternateTag` is not modified. template @@ -230,7 +230,7 @@ struct BerUniversalTagNumber { /// specified `formattingMode` using the specified `options`. The /// behavior is undefined if the type category of `object` and the /// `formattingMode` do not permit a universal tag number (see - /// {DESCRIPTION} for allowed type categories and formatting modes). + /// [](#DESCRIPTION) for allowed type categories and formatting modes). template static Value select(const TYPE& object, int formattingMode, diff --git a/groups/bal/balcl/doc/balcl.txt b/groups/bal/balcl/doc/balcl.txt index 0b2f64a268..3cf62d758b 100644 --- a/groups/bal/balcl/doc/balcl.txt +++ b/groups/bal/balcl/doc/balcl.txt @@ -4,69 +4,69 @@ @MNEMONIC: Basic Application Library Command Line (balcl) -@DESCRIPTION: The 'balcl' package provides a set of components that enable +@DESCRIPTION: The `balcl` package provides a set of components that enable users to access information from the process's command line via a - value-semantic class, 'balcl::CommandLine'. An {Overview} is provided below. - Full details can be found in the documentation of {'balcl_commandline'} and + value-semantic class, `balcl::CommandLine`. + Full details can be found in the documentation of `balcl_commandline` and the other components of this package. /Overview /-------- - There are several steps to using 'balcl::CommandLine': + There are several steps to using `balcl::CommandLine`: -: 1 Specify the set of command-line options (and their attributes) that are -: allowed on the command line by creation of a table of 'balcl::OptionInfo' -: or 'balcl::Option' objects. See {Option Attributes} below. -: -: 2 Create a 'balcl::CommandLine' object from the command-line-option -: specification table. -: -: 3 Pass command-line information (i.e., 'argv') to the 'parse' method of the -: 'balcl::CommandLine' object. -: -: 4 If the 'parse' method is successful, use 'balcl::CommandLine' accessors or -: the accessors of a returned 'balcl::CommandLineOptionsHandle' object. Note -: that options that were defined by the user but did not appear in the -: command line (i.e., the input to 'parse') are left in a "null" state unless -: the user also defined a default value for the option (see {Option -: Attributes}). + 1. Specify the set of command-line options (and their attributes) that are + allowed on the command line by creation of a table of `balcl::OptionInfo` + or `balcl::Option` objects. See {Option Attributes} below. + + 2. Create a `balcl::CommandLine` object from the command-line-option + specification table. + + 3. Pass command-line information (i.e., `argv`) to the `parse` method of the + `balcl::CommandLine` object. + + 4. If the `parse` method is successful, use `balcl::CommandLine` accessors or + the accessors of a returned `balcl::CommandLineOptionsHandle` object. Note + that options that were defined by the user but did not appear in the + command line (i.e., the input to `parse`) are left in a "null" state unless + the user also defined a default value for the option (see + [](#Option Attributes)). /Option Attributes /----------------- This package provides a rich set of features for users to define their allowed options. These include: -: o The names by which the option can be specified on the command line (a long -: tag name and, optionally, a short tag name) as well as a separate name by -: which, after a successful parse, the value of the option can be -: programmatically accessed. -: -: o A description that is later used by the 'printUsage' method. -: -: o Whether or not the option must appear on the command line for a successful -: parse. -: -: o Whether or not the option description will be included in the output -: of the 'printUsage' method. -: -: o Is the option a simple "flag" (a boolean option, either present on the -: command line or not) or does the option have a value? -: -: o If the option has a value, the user can specify: -: o The type of the option value. -: o Whether the option value is scalar or an array. -: o Optionally: A default value for the option. -: o Optionally: A user-supplied functor (a "constraint") to validate the -: value. -: -: o Optionally, the user can supply the address of a variable that is "linked" -: to the option. If so, after a successful parse, the option value can be -: obtained from the variable (an alternative to using the -: 'balcl::CommandLine' accessors). + * The names by which the option can be specified on the command line (a long + tag name and, optionally, a short tag name) as well as a separate name by + which, after a successful parse, the value of the option can be + programmatically accessed. + + * A description that is later used by the `printUsage` method. + + * Whether or not the option must appear on the command line for a successful + parse. + + * Whether or not the option description will be included in the output + of the `printUsage` method. + + * Is the option a simple "flag" (a boolean option, either present on the + command line or not) or does the option have a value? + + * If the option has a value, the user can specify: + - The type of the option value. + - Whether the option value is scalar or an array. + - Optionally: A default value for the option. + - Optionally: A user-supplied functor (a "constraint") to validate the + value. + + * Optionally, the user can supply the address of a variable that is "linked" + to the option. If so, after a successful parse, the option value can be + obtained from the variable (an alternative to using the + `balcl::CommandLine` accessors). /Hierarchical Synopsis /--------------------- - The 'balcl' package currently has 8 components having 6 levels of physical + The `balcl` package currently has 8 components having 6 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical. diff --git a/groups/bdl/bdljsn/bdljsn_error.h b/groups/bdl/bdljsn/bdljsn_error.h index 46d0b8363c..ad7fc39d78 100644 --- a/groups/bdl/bdljsn/bdljsn_error.h +++ b/groups/bdl/bdljsn/bdljsn_error.h @@ -40,13 +40,12 @@ BSLS_IDENT("$Id: $") // // First, we define the function signature: // ``` +// /// Load to the specified `value` the `int` value represented by the +// /// specified `inputText`. Return 0 on success, and a non-zero value +// /// otherwise with no effect on `*value` and the specified `error` is set. // int extractIntegerToken(int *value, // bdljsn::Error *error, // bsl::string_view inputText) -// // Load to the specified 'value' the 'int' value represented by the -// // specified 'inputText'. Return 0 on success, and a non-zero value -// // otherwise with no effect on '*value' and the specified 'error' is -// // set. // { // BSLS_ASSERT(value); // BSLS_ASSERT(error); @@ -104,12 +103,10 @@ namespace bdljsn { // class Error // =========== -/// This unconstrained (value-semantic) attribute class specifies a -/// description of an error in processing a (JSON) document. See the -/// {Attributes} section under {DESCRIPTION} in the component-level -/// documentation for information on the class attributes. Note that the -/// class invariants are identically the constraints on the individual -/// attributes. +/// This unconstrained (value-semantic) attribute class specifies a description +/// of an error in processing a (JSON) document. See the [](#Attributes) for +/// information on the class attributes. Note that the class invariants are +/// identically the constraints on the individual attributes. class Error { // DATA @@ -127,39 +124,39 @@ class Error { // CREATORS /// Create an `Error` object having the default value (see - /// {Attributes}). Optionally specify a `basicAllocator` used to supply + /// [](#Attributes)). Optionally specify a `basicAllocator` used to supply /// memory. If `basicAllocator` is 0, the currently installed default /// allocator is used. Error(); explicit Error(bslma::Allocator *basicAllocator); - /// Create an `Error` object having the specified `location` and - /// `message`. Optionally specify a `basicAllocator` used to supply - /// memory. If `basicAllocator` is 0, the currently installed default - /// allocator is used. + /// Create an `Error` object having the specified `location` and `message`. + /// Optionally specify a `basicAllocator` used to supply memory. If + /// `basicAllocator` is 0, the currently installed default allocator is + /// used. Error(const Location& location, const bsl::string_view& message, bslma::Allocator *basicAllocator = 0); - /// Create an `Error` object having the value of the specified - /// `original` object. Optionally specify a `basicAllocator` used to - /// supply memory. If `basicAllocator` is 0, the currently installed - /// default allocator is used. + /// Create an `Error` object having the value of the specified `original` + /// object. Optionally specify a `basicAllocator` used to supply memory. + /// If `basicAllocator` is 0, the currently installed default allocator is + /// used. Error(const Error& original, bslma::Allocator *basicAllocator = 0); - /// Create a `Error` object having the same value and the same allocator - /// as the specified `original` object. The value of `original` becomes + /// Create a `Error` object having the same value and the same allocator as + /// the specified `original` object. The value of `original` becomes /// unspecified but valid, and its allocator remains unchanged. Error(bslmf::MovableRef original) BSLS_KEYWORD_NOEXCEPT; /// Create a `Error` object having the same value as the specified - /// `original` object, and using the specified `basicAllocator` to - /// supply memory. If `basicAllocator` is 0, the currently installed - /// default allocator is used. The allocator of `original` remains - /// unchanged. If `original` and the newly created object have the same - /// allocator then the value of `original` becomes unspecified but - /// valid, and no exceptions will be thrown; otherwise `original` is - /// unchanged and an exception may be thrown. + /// `original` object, and using the specified `basicAllocator` to supply + /// memory. If `basicAllocator` is 0, the currently installed default + /// allocator is used. The allocator of `original` remains unchanged. If + /// `original` and the newly created object have the same allocator then + /// the value of `original` becomes unspecified but valid, and no + /// exceptions will be thrown; otherwise `original` is unchanged and an + /// exception may be thrown. Error(bslmf::MovableRef original, bslma::Allocator *basicAllocator); @@ -173,19 +170,18 @@ class Error { Error& operator=(const Error& rhs); /// Assign to this object the value of the specified `rhs` object, and - /// return a non-`const` reference to this object. The allocators of - /// this object and `rhs` both remain unchanged. If `rhs` and this - /// object have the same allocator then the value of `rhs` becomes - /// unspecified but valid, and no exceptions will be thrown; otherwise - /// `rhs` is unchanged (and an exception may be thrown). + /// return a non-`const` reference to this object. The allocators of this + /// object and `rhs` both remain unchanged. If `rhs` and this object have + /// the same allocator then the value of `rhs` becomes unspecified but + /// valid, and no exceptions will be thrown; otherwise `rhs` is unchanged + /// (and an exception may be thrown). Error& operator=(bslmf::MovableRef rhs); /// Reset this object to the default value (i.e., its value upon default /// construction). Error& reset(); - /// Set the `location` attribute of this object to the specified - /// `value`. + /// Set the `location` attribute of this object to the specified `value`. Error& setLocation(const Location& value); /// Set the `message` attribute of this object to the specified `value`. @@ -209,23 +205,23 @@ class Error { // Aspects - /// Return the allocator used by this object to supply memory. Note - /// that if no allocator was supplied at construction the default - /// allocator in effect at construction is used. + /// Return the allocator used by this object to supply memory. Note that + /// if no allocator was supplied at construction the default allocator in + /// effect at construction is used. bslma::Allocator *allocator() const; /// Write the value of this object to the specified output `stream` in a - /// human-readable format, and return a non-`const` reference to - /// `stream`. Optionally specify an initial indentation `level`, whose - /// absolute value is incremented recursively for nested objects. If - /// `level` is specified, optionally specify `spacesPerLevel`, whose - /// absolute value indicates the number of spaces per indentation level - /// for this and all of its nested objects. If `level` is negative, - /// suppress indentation of the first line. If `spacesPerLevel` is - /// negative, format the entire output on one line, suppressing all but - /// the initial indentation (as governed by `level`). If `stream` is - /// not valid on entry, this operation has no effect. Note that the - /// format is not fully specified, and can change without notice. + /// human-readable format, and return a non-`const` reference to `stream`. + /// Optionally specify an initial indentation `level`, whose absolute value + /// is incremented recursively for nested objects. If `level` is + /// specified, optionally specify `spacesPerLevel`, whose absolute value + /// indicates the number of spaces per indentation level for this and all + /// of its nested objects. If `level` is negative, suppress indentation of + /// the first line. If `spacesPerLevel` is negative, format the entire + /// output on one line, suppressing all but the initial indentation (as + /// governed by `level`). If `stream` is not valid on entry, this + /// operation has no effect. Note that the format is not fully specified, + /// and can change without notice. bsl::ostream& print(bsl::ostream& stream, int level = 0, int spacesPerLevel = 4) const; @@ -233,31 +229,29 @@ class Error { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` attribute objects have -/// the same value, and `false` otherwise. Two attribute objects have the -/// same value if each respective attribute has the same value. +/// Return `true` if the specified `lhs` and `rhs` attribute objects have the +/// same value, and `false` otherwise. Two attribute objects have the same +/// value if each respective attribute has the same value. bool operator==(const Error& lhs, const Error& rhs); /// Return `true` if the specified `lhs` and `rhs` attribute objects do not -/// have the same value, and `false` otherwise. Two attribute objects do -/// not have the same value if one or more respective attributes differ in -/// values. +/// have the same value, and `false` otherwise. Two attribute objects do not +/// have the same value if one or more respective attributes differ in values. bool operator!=(const Error& lhs, const Error& rhs); -/// Write the value of the specified `object` to the specified output -/// `stream` in a single-line format, and return a non-`const` reference to -/// `stream`. If `stream` is not valid on entry, this operation has no -/// effect. Note that this human-readable format is not fully specified and -/// can change without notice. Also note that this method has the same -/// behavior as `object.print(stream, 0, -1)`, but with the attribute names -/// elided. +/// Write the value of the specified `object` to the specified output `stream` +/// in a single-line format, and return a non-`const` reference to `stream`. +/// If `stream` is not valid on entry, this operation has no effect. Note that +/// this human-readable format is not fully specified and can change without +/// notice. Also note that this method has the same behavior as +/// `object.print(stream, 0, -1)`, but with the attribute names elided. bsl::ostream& operator<<(bsl::ostream& stream, const Error& object); // FREE FUNCTIONS /// Pass the specified `object` to the specified `hashAlgorithm`. This -/// function integrates with the `bslh` modular hashing system and -/// effectively provides a `bsl::hash` specialization for `ErroError`. +/// function integrates with the `bslh` modular hashing system and effectively +/// provides a `bsl::hash` specialization for `ErroError`. template void hashAppend(HASHALG& hashAlgorithm, const Error& object); diff --git a/groups/bdl/bdljsn/bdljsn_location.h b/groups/bdl/bdljsn/bdljsn_location.h index c0ef95e8f6..a1f1218d04 100644 --- a/groups/bdl/bdljsn/bdljsn_location.h +++ b/groups/bdl/bdljsn/bdljsn_location.h @@ -16,8 +16,8 @@ BSLS_IDENT("$Id: $") // (value-semantic) attribute class, `bdljsn::Location`, that is used to // describe a location in a (JSON) document. Location is expressed by the // `offset` (attrbute) in bytes from the start of the document. See -// {`jsonutil`} for utilities that may provide `bdljsn::Location` values when -// reporting error states. +// `bdljson_jsonutil` for utilities that may provide `bdljsn::Location` values +// when reporting error states. // ///Attributes ///---------- @@ -116,11 +116,10 @@ namespace bdljsn { // class Location // ============== -/// This unconstrained (value-semantic) attribute class specifies a location -/// in a (JSON) document. See the {Attributes} section under {DESCRIPTION} -/// in the component-level documentation for information on the class -/// attributes. Note that the class invariants are identically the -/// constraints on the individual attributes. +/// This unconstrained (value-semantic) attribute class specifies a location in +/// a (JSON) document. See the [](#Attributes) for information on the class +/// attributes. Note that the class invariants are identically the constraints +/// on the individual attributes. class Location { // DATA @@ -175,17 +174,16 @@ class Location { // Aspects - /// Format this object to the specified output `stream` at the - /// optionally specified indentation `level` and return a reference to - /// the modifiable `stream`. If `level` is specified, optionally - /// specify `spacesPerLevel`, the number of spaces per indentation level - /// for this and all of its nested objects. Each line is indented by - /// the absolute value of `level * spacesPerLevel`. If `level` is - /// negative, suppress indentation of the first line. If - /// `spacesPerLevel` is negative, suppress line breaks and format the - /// entire output on one line. If `stream` is initially invalid, this - /// operation has no effect. Note that a trailing newline is provided - /// in multiline mode only. + /// Format this object to the specified output `stream` at the optionally + /// specified indentation `level` and return a reference to the modifiable + /// `stream`. If `level` is specified, optionally specify + /// `spacesPerLevel`, the number of spaces per indentation level for this + /// and all of its nested objects. Each line is indented by the absolute + /// value of `level * spacesPerLevel`. If `level` is negative, suppress + /// indentation of the first line. If `spacesPerLevel` is negative, + /// suppress line breaks and format the entire output on one line. If + /// `stream` is initially invalid, this operation has no effect. Note that + /// a trailing newline is provided in multiline mode only. bsl::ostream& print(bsl::ostream& stream, int level = 0, int spacesPerLevel = 4) const; @@ -193,33 +191,31 @@ class Location { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` attribute objects have -/// the same value, and `false` otherwise. Two attribute objects have the -/// same value if each respective attribute has the same value. +/// Return `true` if the specified `lhs` and `rhs` attribute objects have the +/// same value, and `false` otherwise. Two attribute objects have the same +/// value if each respective attribute has the same value. inline bool operator==(const Location& lhs, const Location& rhs); /// Return `true` if the specified `lhs` and `rhs` attribute objects do not -/// have the same value, and `false` otherwise. Two attribute objects do -/// not have the same value if one or more respective attributes differ in -/// values. +/// have the same value, and `false` otherwise. Two attribute objects do not +/// have the same value if one or more respective attributes differ in values. inline bool operator!=(const Location& lhs, const Location& rhs); -/// Write the value of the specified `object` to the specified output -/// `stream` in a single-line format, and return a non-`const` reference to -/// `stream`. If `stream` is not valid on entry, this operation has no -/// effect. Note that this human-readable format is not fully specified and -/// can change without notice. Also note that this method has the same -/// behavior as `object.print(stream, 0, -1)`, but with the attribute names -/// elided. +/// Write the value of the specified `object` to the specified output `stream` +/// in a single-line format, and return a non-`const` reference to `stream`. +/// If `stream` is not valid on entry, this operation has no effect. Note that +/// this human-readable format is not fully specified and can change without +/// notice. Also note that this method has the same behavior as +/// `object.print(stream, 0, -1)`, but with the attribute names elided. bsl::ostream& operator<<(bsl::ostream& stream, const Location& object); // FREE FUNCTIONS /// Pass the specified `object` to the specified `hashAlg`. This function -/// integrates with the `bslh` modular hashing system and effectively -/// provides a `bsl::hash` specialization for `Location`. +/// integrates with the `bslh` modular hashing system and effectively provides +/// a `bsl::hash` specialization for `Location`. template void hashAppend(HASHALG& hashAlg, const Location& object); diff --git a/groups/bdl/bdljsn/bdljsn_readoptions.h b/groups/bdl/bdljsn/bdljsn_readoptions.h index ca46893017..c4f2910936 100644 --- a/groups/bdl/bdljsn/bdljsn_readoptions.h +++ b/groups/bdl/bdljsn/bdljsn_readoptions.h @@ -14,7 +14,7 @@ BSLS_IDENT("$Id: $") // //@DESCRIPTION: This component provides a single, simply constrained // (value-semantic) attribute class, `bdljsn::ReadOptions`, that is used to -// specify options for reading a JSON document (see {`bdljsn_jsonutil`}). +// specify options for reading a JSON document (see `bdljsn_jsonutil`). // ///Attributes ///---------- @@ -76,11 +76,10 @@ namespace bdljsn { // class ReadOptions // ================= -/// This simply constrained (value-semantic) attribute class specifies -/// options for reading a JSON document. See the {Attributes} section under -/// {DESCRIPTION} in the component-level documentation for information on -/// the class attributes. Note that the class invariants are identically -/// the constraints on the individual attributes. +/// This simply constrained (value-semantic) attribute class specifies options +/// for reading a JSON document. See the [](#Attributes) for information on +/// the class attributes. Note that the class invariants are identically the +/// constraints on the individual attributes. class ReadOptions { // INSTANCE DATA @@ -99,8 +98,8 @@ class ReadOptions { public: // CREATORS - /// Create an object of type `ReadOptions` having the (default) - /// attribute values: + /// Create an object of type `ReadOptions` having the (default) attribute + /// values: /// ``` /// setAllowTrailingText() == false /// maxNestedDepth() == 64 @@ -143,18 +142,17 @@ class ReadOptions { // Aspects - /// Format this object to the specified output `stream` at the - /// optionally specified indentation `level` and return a reference to - /// the modifiable `stream`. If `level` is specified, optionally - /// specify `spacesPerLevel`, the number of spaces per indentation level - /// for this and all of its nested objects. Each line is indented by - /// the absolute value of `level * spacesPerLevel`. If `level` is - /// negative, suppress indentation of the first line. If - /// `spacesPerLevel` is negative, suppress line breaks and format the - /// entire output on one line. If `stream` is initially invalid, this - /// operation has no effect. Note that a trailing newline is provided - /// in multiline mode only. Also note that the format is not fully - /// specified, and can change without notice. + /// Format this object to the specified output `stream` at the optionally + /// specified indentation `level` and return a reference to the modifiable + /// `stream`. If `level` is specified, optionally specify + /// `spacesPerLevel`, the number of spaces per indentation level for this + /// and all of its nested objects. Each line is indented by the absolute + /// value of `level * spacesPerLevel`. If `level` is negative, suppress + /// indentation of the first line. If `spacesPerLevel` is negative, + /// suppress line breaks and format the entire output on one line. If + /// `stream` is initially invalid, this operation has no effect. Note that + /// a trailing newline is provided in multiline mode only. Also note that + /// the format is not fully specified, and can change without notice. bsl::ostream& print(bsl::ostream& stream, int level = 0, int spacesPerLevel = 4) const; @@ -162,16 +160,16 @@ class ReadOptions { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` attribute objects have -/// the same value, and `false` otherwise. Two attribute objects have the -/// same value if each respective attribute has the same value. +/// Return `true` if the specified `lhs` and `rhs` attribute objects have the +/// same value, and `false` otherwise. Two attribute objects have the same +/// value if each respective attribute has the same value. inline bool operator==(const ReadOptions& lhs, const ReadOptions& rhs); /// Return `true` if the specified `lhs` and `rhs` attribute objects do not -/// have the same value, and `false` otherwise. Two attribute objects do -/// not have the same value if one or more respective attributes do not -/// have the same value. +/// have the same value, and `false` otherwise. Two attribute objects do not +/// have the same value if one or more respective attributes do not have the +/// same value. inline bool operator!=(const ReadOptions& lhs, const ReadOptions& rhs); diff --git a/groups/bdl/bdljsn/bdljsn_stringutil.h b/groups/bdl/bdljsn/bdljsn_stringutil.h index e2f8fd0073..43504cf348 100644 --- a/groups/bdl/bdljsn/bdljsn_stringutil.h +++ b/groups/bdl/bdljsn/bdljsn_stringutil.h @@ -152,9 +152,8 @@ BSLS_IDENT("$Id: $") // Finally, we convert the `jsonCompatibleString` back to its original content: // ``` // bsl::string fromJsonString; -// const int rcDecode = bdljsn::StringUtil::readString( -// &fromJsonString, -// jsonCompatibleString); +// const int rcDecode = bdljsn::StringUtil::readString(&fromJsonString, +// jsonCompatibleString); // assert(0 == rcDecode); // assert(initial == fromJsonString); // @@ -182,8 +181,8 @@ namespace bdljsn { // ================= /// This class provides utility functions for converting arbitrary UTF-8 -/// sequences into JSON strings and visa versa. See {JSON Strings} in -/// {DESCRIPTION} for details of these transformations. +/// sequences into JSON strings and visa versa. See [](#JSON Strings) for +/// details of these transformations. struct StringUtil { public: @@ -195,21 +194,21 @@ struct StringUtil { // CLASS METHODS - /// Load to the specified `value` the UTF-8 codepoint sequence - /// equivalent to the specified (JSON) `string` (see {JSON Strings}). - /// Return 0 on success and a non-zero value otherwise. Optionally - /// specify `flags` to request variances from certain rules of JSON - /// decoding (see {Strictness}). + /// Load to the specified `value` the UTF-8 codepoint sequence equivalent + /// to the specified (JSON) `string` (see [](#JSON Strings)). Return 0 on + /// success and a non-zero value otherwise. Optionally specify `flags` to + /// request variances from certain rules of JSON decoding (see + /// [](#Strictness)). static int readString(bsl::string *value, const bsl::string_view& string, int flags = e_NONE); - /// Load to the specified `value` the UTF-8 codepoint sequence - /// equivalent to the specified `string`, that is JSON-compliant absent - /// the leading and trailing double quote characters (see {JSON - /// Strings}). Return 0 on success and a non-zero value otherwise. - /// Optionally specify `flags` to request variances from certain rules - /// of JSON decoding (see {Strictness}). + /// Load to the specified `value` the UTF-8 codepoint sequence equivalent + /// to the specified `string`, that is JSON-compliant absent the leading + /// and trailing double quote characters (see [](#JSON Strings)). Return 0 + /// on success and a non-zero value otherwise. Optionally specify `flags` + /// to request variances from certain rules of JSON decoding (see + /// [](#Strictness)). static int readUnquotedString(bsl::string *value, const bsl::string_view& string, int flags = e_NONE); @@ -217,9 +216,9 @@ struct StringUtil { /// Write to the specified `stream` a JSON-compliant string that is /// equivalent to the specified `string`, an arbitrary UTF-8 codepoint /// sequence. Return 0 on success and a non-zero value otherwise. The - /// operation fails if `string` is not a sequence of UTF-8 codepoints or - /// if there is an error writing to `stream`. See {Conventions: - /// Arbitrary UTF-8 to JSON String} for further details. + /// operation fails if `string` is not a sequence of UTF-8 codepoints or if + /// there is an error writing to `stream`. See + /// [](#Guarantees: Arbitrary UTF-8 to JSON String) for further details. static int writeString(bsl::ostream& stream, const bsl::string_view& string); }; diff --git a/groups/bdl/bdljsn/bdljsn_writeoptions.h b/groups/bdl/bdljsn/bdljsn_writeoptions.h index 8d28da3cc0..d51eec6fa3 100644 --- a/groups/bdl/bdljsn/bdljsn_writeoptions.h +++ b/groups/bdl/bdljsn/bdljsn_writeoptions.h @@ -14,7 +14,7 @@ BSLS_IDENT("$Id: $") // //@DESCRIPTION: This component provides a single, simply constrained // (value-semantic) attribute class, `bdljsn::WriteOptions`, that is used to -// specify options for writing a JSON document (see {`bdljsn_jsonutil`}). +// specify options for writing a JSON document (see `bdljsn_jsonutil`). // ///Attributes ///---------- @@ -82,11 +82,10 @@ namespace bdljsn { // class WriteOptions // ================== -/// This simply constrained (value-semantic) attribute class specifies -/// options for writing a JSON document. See the {Attributes} section under -/// {DESCRIPTION} in the component-level documentation for information on -/// the class attributes. Note that the class invariants are identically -/// the constraints on the individual attributes. +/// This simply constrained (value-semantic) attribute class specifies options +/// for writing a JSON document. See the [](#Attributes) for information on +/// the class attributes. Note that the class invariants are identically the +/// constraints on the individual attributes. class WriteOptions { // INSTANCE DATA @@ -144,13 +143,13 @@ class WriteOptions { /// construction) and return a non-`const` reference to this object. WriteOptions& reset(); - /// Set the `initialIndentLevel` attribute of this object to the - /// specified `value` and return a non-`const` reference to this object. - /// The behavior is undefined unless `0 <= value`. + /// Set the `initialIndentLevel` attribute of this object to the specified + /// `value` and return a non-`const` reference to this object. The + /// behavior is undefined unless `0 <= value`. WriteOptions& setInitialIndentLevel(int value); - /// Set the `sortMembers` attribute of this object to the specified - /// `value` and return a non-`const` reference to this object. + /// Set the `sortMembers` attribute of this object to the specified `value` + /// and return a non-`const` reference to this object. WriteOptions& setSortMembers(bool value); /// Set the `spacesPerLevel` attribute of this object to the specified @@ -158,8 +157,8 @@ class WriteOptions { /// behavior is undefined unless `0 <= value`. WriteOptions& setSpacesPerLevel(int value); - /// Set the `style` attribute of this object to the specified `value`. - /// and return a non-`const` reference to this object. + /// Set the `style` attribute of this object to the specified `value` and + /// return a non-`const` reference to this object. WriteOptions& setStyle(bdljsn::WriteStyle::Enum value); // ACCESSORS @@ -197,16 +196,15 @@ class WriteOptions { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` attribute objects have -/// the same value, and `false` otherwise. Two attribute objects have the -/// same value if each respective attribute has the same value. +/// Return `true` if the specified `lhs` and `rhs` attribute objects have the +/// same value, and `false` otherwise. Two attribute objects have the same +/// value if each respective attribute has the same value. inline bool operator==(const WriteOptions& lhs, const WriteOptions& rhs); /// Return `true` if the specified `lhs` and `rhs` attribute objects do not -/// have the same value, and `false` otherwise. Two attribute objects do -/// not have the same value if one or more respective attributes differ in -/// values. +/// have the same value, and `false` otherwise. Two attribute objects do not +/// have the same value if one or more respective attributes differ in values. inline bool operator!=(const WriteOptions& lhs, const WriteOptions& rhs); diff --git a/groups/bdl/bdlmt/bdlmt_signaler.h b/groups/bdl/bdlmt/bdlmt_signaler.h index 8b7bc3eb01..50ca12a360 100644 --- a/groups/bdl/bdlmt/bdlmt_signaler.h +++ b/groups/bdl/bdlmt/bdlmt_signaler.h @@ -26,15 +26,15 @@ BSLS_IDENT("$Id: $") // destruction is available in `bdlmt::SignalerConnectionGuard`. // // Signalers and the slots connected to them are all managed. Any connections -// will be automatically disconnected when a `Signaler` is destroyed, or when -// explicitly disconnected, and all internally allocated resources will be +// will be automatically disconnected when a `bdlmt::Signaler` is destroyed, or +// when explicitly disconnected, and all internally allocated resources will be // destroyed when no more references to them remain. This enables the user to // make signaler/slot connections and emit signals without expanding effort on // managing the lifetimes of any of the involved objects. // ///Slot Object Requirements ///------------------------ -// Slots connected to a signaler `Signaler` must be callable and +// Slots connected to a signaler `bdlmt::Signaler` must be callable and // copyable objects that may be passed to the constructor of // `bsl::function`. I.e. a slot must be callable with the same // arguments as `t_PROT`, and if a slot returns a value it will be discarded. @@ -65,9 +65,10 @@ BSLS_IDENT("$Id: $") // ///Comparison of `SignalerConnection`s ///----------------------------------- -// Ordering comparisons of `SignalerConnection`s are transitive and are +// Ordering comparisons of `bdlmt::SignalerConnection`s are transitive and are // provided to facilitate their being stored in an associative container. The -// ordering of a `SignalerConnection` does not change when it is disconnected. +// ordering of a `bdlmt::SignalerConnection` does not change when it is +// disconnected. // // In equality comparisons, two default constructed connections compare // equivalent and a default constructed connection is never equivalent to a @@ -76,8 +77,8 @@ BSLS_IDENT("$Id: $") // ///Thread Safety ///------------- -// `bdlmt::Signaler` is fully thread-safe, meaning that multiple threads may -// use their own instances of the class or use a shared instance without +// `bdlmt::Signaler` is **fully thread-safe**, meaning that multiple threads +// may use their own instances of the class or use a shared instance without // further synchronization. // // With the exception of assignment operators, `swap()`, `reset()` and @@ -92,6 +93,10 @@ BSLS_IDENT("$Id: $") // ///Usage ///----- +// This section illustrates intended use of this component. +// +///Example 1: Basic Usege +/// - - - - - - - - - - - // Suppose we want to implement a GUI button class that allows users to // keep track of its `press` events. // @@ -240,22 +245,19 @@ struct Signaler_NotArg { /// For a function prototype `t_PROT` of up to 9 arguments, provide types /// `ForwardingTypeN` which is the most convenient way to forward the `Nth` /// argument. -/// * as the type of argument N itself (in the case of some fundamental -/// types) +/// * as the type of argument N itself (in the case of some fundamental types) /// * as a const reference (if `TypeN` is large and either by value or by /// const reference), or /// * as a reference to a modifiable object, if that's how the argument was /// passed in the first place. /// Note that nothing is passed as an rvalue reference, since if there are +/// multiple slots (usually the case), the argument will be moved from by the +/// first one and then unsuitable to be used by the ones following. +/// +/// Also provide `ForwardingNotArg` the type that forwards `Signaler_NotArg`. template struct Signaler_ArgumentType { - // multiple slots (usually the case), the argument will be moved from by - // the first one and then unsuitable to be used by the ones following. - // - // Also provide 'ForwardingNotArg' the type that forwards - // 'Signaler_NotArg'. - private: // PRIVATE TYPES typedef typename bslmf::FunctionPointerTraits::ArgumentList Args; @@ -289,8 +291,8 @@ struct Signaler_ArgumentType { // struct Signaler_Invocable // ========================= -/// Provides a call operator for the derived class `bdlmt::Signaler`, such -/// that its call signature is identical to that of `t_PROT`. +/// Provides a call operator for the derived class `bdlmt::Signaler`, such that +/// its call signature is identical to that of `t_PROT`. template struct Signaler_Invocable { }; @@ -300,9 +302,9 @@ struct Signaler_Invocable { // ACCESSOR /// Call the functions held in all slot holders, in the order of group - /// numbers and with the ordering within one group being the order in - /// which connections were made, passing the number and type of - /// arguments passed to this function. + /// numbers and with the ordering within one group being the order in which + /// connections were made, passing the number and type of arguments passed + /// to this function. void operator()() const; }; @@ -311,9 +313,9 @@ struct Signaler_Invocable { // ACCESSOR /// Call the functions held in all slot holders, in the order of group - /// numbers and with the ordering within one group being the order in - /// which connections were made, passing the number and type of - /// arguments passed to this function. + /// numbers and with the ordering within one group being the order in which + /// connections were made, passing the number and type of arguments passed + /// to this function. void operator()(t_ARG1) const; }; @@ -322,9 +324,9 @@ struct Signaler_Invocable { // ACCESSOR /// Call the functions held in all slot holders, in the order of group - /// numbers and with the ordering within one group being the order in - /// which connections were made, passing the number and type of - /// arguments passed to this function. + /// numbers and with the ordering within one group being the order in which + /// connections were made, passing the number and type of arguments passed + /// to this function. void operator()(t_ARG1, t_ARG2) const; }; @@ -333,9 +335,9 @@ struct Signaler_Invocable { // ACCESSOR /// Call the functions held in all slot holders, in the order of group - /// numbers and with the ordering within one group being the order in - /// which connections were made, passing the number and type of - /// arguments passed to this function. + /// numbers and with the ordering within one group being the order in which + /// connections were made, passing the number and type of arguments passed + /// to this function. void operator()(t_ARG1, t_ARG2, t_ARG3) const; }; @@ -348,9 +350,9 @@ struct Signaler_Invocable { // ACCESSOR /// Call the functions held in all slot holders, in the order of group - /// numbers and with the ordering within one group being the order in - /// which connections were made, passing the number and type of - /// arguments passed to this function. + /// numbers and with the ordering within one group being the order in which + /// connections were made, passing the number and type of arguments passed + /// to this function. void operator()(t_ARG1, t_ARG2, t_ARG3, t_ARG4) const; }; @@ -365,9 +367,9 @@ struct Signaler_Invocable class Signaler_SlotNode : public Signaler_SlotNode_Base { @@ -543,20 +544,20 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { public: // PUBLIC TYPE - /// Defines a "key" used to index slots in an associative collection. - /// The first element of the pair is the slot call group; the second is - /// the slot ID. + /// Defines a "key" used to index slots in an associative collection. The + /// first element of the pair is the slot call group; the second is the + /// slot ID. typedef bsl::pair SlotMapKey; private: // PRIVATE DATA - // Slot key containing the call group and the slot ID. Used when - // notifying the signaler about disconnection. + // Slot key containing the call group and the slot ID. Used when notifying + // the signaler about disconnection. SlotMapKey d_slotMapKey; - // Set to `true` on construction, and to `false` on disconnection. - // Used for preventing calling a slot after it has been disconnected. + // Set to `true` on construction, and to `false` on disconnection. Used + // for preventing calling a slot after it has been disconnected. bsls::AtomicBool d_isConnected; // Weak reference to the associated signaler node. @@ -576,10 +577,10 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { // PRIVATE ACCESSORS /// Dispatch function to be called by the `invoke` function, the first - /// argument is an `integral_constant` containing the number of - /// specified arguments `argN` that follow it. Each function takes 9 - /// arguments in addition to the integral constant, but the last ones of - /// type `ForwardingNotArg` are not used. + /// argument is an `integral_constant` containing the number of specified + /// arguments `argN` that follow it. Each function takes 9 arguments in + /// addition to the integral constant, but the last ones of type + /// `ForwardingNotArg` are not used. void doInvoke(bsl::integral_constant, // arguments count tag ForwardingNotArg, ForwardingNotArg, @@ -686,8 +687,8 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { /// Create a `Signaler_SlotNode` object associated with signaler node at /// the specified `signalerNodePtr` using the specified `slotMapKey` and - /// with the specified `slot` callable object. Specify an `allocator` - /// used to supply memory. + /// with the specified `slot` callable object. Specify an `allocator` used + /// to supply memory. template Signaler_SlotNode( const bsl::weak_ptr& signalerNodePtr, @@ -704,23 +705,22 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { /// Disconnect this slot and return without waiting. If the slot was /// already disconnected, this function has no effect. Throws nothing. /// Note that it is guaranteed that this slot will not be called by a - /// signal on the same signaler that begins after this function - /// completes. + /// signal on the same signaler that begins after this function completes. void disconnect() BSLS_KEYWORD_NOEXCEPT BSLS_KEYWORD_OVERRIDE; /// Disconnect this slot and block the calling thread pending the /// completion of signals being emitted on the signaler by any other /// threads. If the slot was already disconnected, this function has no - /// effect on the slot. Throws nothing. The behavior is undefined if - /// this function is called from a slot on the same signaler. Note that - /// it is guaranteed that this slot will not be called by a signal on - /// the same signaler that begins after this function completes, whether - /// `wait` is `true` or not. + /// effect on the slot. Throws nothing. The behavior is undefined if this + /// function is called from a slot on the same signaler. Note that it is + /// guaranteed that this slot will not be called by a signal on the same + /// signaler that begins after this function completes, whether `wait` is + /// `true` or not. void disconnectAndWait() BSLS_KEYWORD_NOEXCEPT BSLS_KEYWORD_OVERRIDE; - /// Notify this slot that is was disconnected from its associated - /// signaler. Throws nothing. After this function completes, - /// `isConnected()` returns `false`. + /// Notify this slot that is was disconnected from its associated signaler. + /// Throws nothing. After this function completes, `isConnected()` returns + /// `false`. void notifyDisconnected() BSLS_KEYWORD_NOEXCEPT; // ACCESSORS @@ -740,8 +740,8 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { typename ArgumentType::ForwardingType8 arg8, typename ArgumentType::ForwardingType9 arg9) const; - /// Return `true` if this slot is connected to its associated signaler, - /// and `false` otherwise. + /// Return `true` if this slot is connected to its associated signaler, and + /// `false` otherwise. bool isConnected() const BSLS_KEYWORD_OVERRIDE; }; @@ -750,12 +750,12 @@ class Signaler_SlotNode : public Signaler_SlotNode_Base { // =================== /// Provides the implementation of a signaler. This object has a 1-1 -/// relationship with the `Signaler`, which has a shared pointer to it. -/// This allows other objects to refer to it via shared and weak pointers. -/// This allows `SignalerConnection` objects to outlive the -/// `Signaler - Signaler_Node` pair, since they can test or lock weak -/// pointers to see if the `Signaler_Node` still exists when they are trying -/// to disconnect themselves. +/// relationship with the `Signaler`, which has a shared pointer to it. This +/// allows other objects to refer to it via shared and weak pointers. This +/// allows `SignalerConnection` objects to outlive the `Signaler - +/// Signaler_Node` pair, since they can test or lock weak pointers to see if +/// the `Signaler_Node` still exists when they are trying to disconnect +/// themselves. template class Signaler_Node : public bsl::enable_shared_from_this > { @@ -777,8 +777,8 @@ class Signaler_Node // diconnects in `wait` mode. mutable bslmt::ReaderWriterMutex d_signalerMutex; - // Thread-safe collection containing slots indexed (and ordered) by - // their respective keys. + // Thread-safe collection containing slots indexed (and ordered) by their + // respective keys. KeyToSlotMap d_slotMap; // For supplying `second` members of the `SlotMapKey` values that are @@ -793,10 +793,10 @@ class Signaler_Node public: // CREATORS - /// Create a `Signaler_Node` object having no connected slots. Specify - /// an `allocator` used to supply memory. Note that the supplied - /// allocator must remain valid until all connection objects associated - /// with this signaler are destroyed. + /// Create a `Signaler_Node` object having no connected slots. Specify an + /// `allocator` used to supply memory. Note that the supplied allocator + /// must remain valid until all connection objects associated with this + /// signaler are destroyed. explicit Signaler_Node(bslma::Allocator *allocator); @@ -1033,8 +1033,7 @@ class Signaler : public Signaler_Invocable, t_PROT> { public: // ACCESSORS - // void operator()(ARGS... args) const; - // + // 'bdlmt::Signaler_Invocable', from which this 'class' inherits, provides // a call operator that, in C++11, would be defined and behave exactly this // way, except that the number of arguments is limited to @@ -1055,6 +1054,8 @@ class Signaler : public Signaler_Invocable, t_PROT> { // called in the traversal. Also note that if execution of a slot throws // an exception, the emission sequence is interrupted and the exception is // propagated to the caller of the signaler immediately. + // void operator()(ARGS... args) const; + // /// Return the number of slots connected to this signaler. Note that /// the value returned by `slotCount()` is approximate if the signaler @@ -1138,9 +1139,8 @@ class SignalerConnection { SignalerConnection& operator=(bslmf::MovableRef rhs) BSLS_KEYWORD_NOEXCEPT; - /// Disassociate this connection object from its associated slot, if - /// any, and reset `*this` to a default-constructed state. Throws - /// nothing. + /// Disassociate this connection object from its associated slot, if any, + /// and reset `*this` to a default-constructed state. Throws nothing. void reset() BSLS_KEYWORD_NOEXCEPT; /// Swap the contents of `*this` and the specified `other`. Throws @@ -1150,31 +1150,29 @@ class SignalerConnection { public: // ACCESSORS - /// Disconnect the associated slot. If the slot was already - /// disconnected, this function has no effect. This function returns - /// immediately without waiting on any calls to the signaler that may be - /// in progress. Any signal emitted on the corresponding signaler that - /// happens after this call to `disconnect` completes will not emit to - /// the slot. Throws nothing. Note that it is unspecified if any - /// signal that is emitted before this function completes will call the - /// slot. + /// Disconnect the associated slot. If the slot was already disconnected, + /// this function has no effect. This function returns immediately without + /// waiting on any calls to the signaler that may be in progress. Any + /// signal emitted on the corresponding signaler that happens after this + /// call to `disconnect` completes will not emit to the slot. Throws + /// nothing. Note that it is unspecified if any signal that is emitted + /// before this function completes will call the slot. void disconnect() const BSLS_KEYWORD_NOEXCEPT; - /// Disconnect the associated slot. If the slot was already - /// disconnected, this function has no effect. This function blocks the - /// calling thread pending completion of signals emitted on the signaler - /// by any thread, even if the slot was disconnected prior to this call. - /// Any signal emitted on the corresponding signaler that happens after - /// this call to `disconnect` completes will not emit to the slot. - /// Throws nothing. The behavior is undefined if this method is called - /// from any slot. Note that it is unspecified if any signal emitted on - /// the signaler that begins before this function completes will call - /// the slot. + /// Disconnect the associated slot. If the slot was already disconnected, + /// this function has no effect. This function blocks the calling thread + /// pending completion of signals emitted on the signaler by any thread, + /// even if the slot was disconnected prior to this call. Any signal + /// emitted on the corresponding signaler that happens after this call to + /// `disconnect` completes will not emit to the slot. Throws nothing. The + /// behavior is undefined if this method is called from any slot. Note + /// that it is unspecified if any signal emitted on the signaler that + /// begins before this function completes will call the slot. void disconnectAndWait() const BSLS_KEYWORD_NOEXCEPT; /// Return `true` if the associated slot is connected to the signaler - /// `*this` was obtained from, and `false` otherwise. If `*this` does - /// not have an associated slot (i.e., was default-constructed), return + /// `*this` was obtained from, and `false` otherwise. If `*this` does not + /// have an associated slot (i.e., was default-constructed), return /// `false`. bool isConnected() const; }; @@ -1183,22 +1181,22 @@ class SignalerConnection { // class SignalerConnectionGuard // ============================= -/// This guard type `has a` `SignalerConnection`, through which it can -/// manage a slot, and when it is destroyed or assigned to it will -/// disconnect that slot. It also contains a boolean `waitOnDisconnect` -/// attribute, which determines whether `disconnect` or `disconnectAndWait` -/// is used to disconnect the slot. The `waitOnDisconnect` attribute is set -/// in constructors from a `SignalerConnection` and propagated when move -/// constructing or move assigning a guard to a different guard. +/// This guard type `has a` `SignalerConnection`, through which it can manage a +/// slot, and when it is destroyed or assigned to it will disconnect that slot. +/// It also contains a boolean `waitOnDisconnect` attribute, which determines +/// whether `disconnect` or `disconnectAndWait` is used to disconnect the slot. +/// The `waitOnDisconnect` attribute is set in constructors from a +/// `SignalerConnection` and propagated when move constructing or move +/// assigning a guard to a different guard. class SignalerConnectionGuard { // PRIVATE DATA SignalerConnection d_connection; bool d_waitOnDisconnect; // determines whether - // 'disconnect' or - // 'disconnectAndWait' is called - // on 'd_connection' at + // `disconnect` or + // `disconnectAndWait` is called + // on `d_connection` at // destruction or assignment private: @@ -1224,8 +1222,8 @@ class SignalerConnectionGuard { /// management of the same slot, if any, as the specified `connection` /// object. Upon destruction or assignment, the optionally specified /// `waitOnDisconnect` determines whether `disconnect` or - /// `disconnectAndWait` will be called on the slot managed by this - /// object, if any. + /// `disconnectAndWait` will be called on the slot managed by this object, + /// if any. explicit SignalerConnectionGuard( const SignalerConnection& connection, @@ -1234,38 +1232,37 @@ class SignalerConnectionGuard { /// Create a `SignalerConnectionGuard` that refers to the same slot, if /// any, as the specified `connection`, which is left in an unspecified /// state. Optionally specify `waitOnDisconnect` indicating whether - /// `disconnect` or `disconnectAndWait` will be called on the slot, if - /// any, managed by this object upon destruction or assignment. Throws - /// nothing. + /// `disconnect` or `disconnectAndWait` will be called on the slot, if any, + /// managed by this object upon destruction or assignment. Throws nothing. explicit SignalerConnectionGuard(bslmf::MovableRef< SignalerConnection> connection, bool waitOnDisconnect = false) BSLS_KEYWORD_NOEXCEPT; - /// Create a `SignalerConnectionGuard` that manages the same slot, if - /// any, as the specified `original`, which is left in the - /// default-constructed state. Copy the `waitOnDisconnect` state from - /// `original`, indicating whether `disconnect()` or - /// `disconnectAndWait()` will be called on the slot, if any, contained - /// in this object upon destruction or assignment. Throws nothing. + /// Create a `SignalerConnectionGuard` that manages the same slot, if any, + /// as the specified `original`, which is left in the default-constructed + /// state. Copy the `waitOnDisconnect` state from `original`, indicating + /// whether `disconnect()` or `disconnectAndWait()` will be called on the + /// slot, if any, contained in this object upon destruction or assignment. + /// Throws nothing. SignalerConnectionGuard(bslmf::MovableRef original) BSLS_KEYWORD_NOEXCEPT; - /// Destroy this object. If a slot is being managed by this object, - /// call `disconnect` or `disconnectAndWait` on it, depending upon the - /// value of `waitOnDisconnect`. + /// Destroy this object. If a slot is being managed by this object, call + /// `disconnect` or `disconnectAndWait` on it, depending upon the value of + /// `waitOnDisconnect`. ~SignalerConnectionGuard(); // MANIPULATORS /// If there is a currently managed slot, call `disconnect` or /// `disconnectAndWait` on it, depending on the value of the - /// `waitOnDisconnect` state. Make this connection refer to the same - /// slot, if any, as the specified `rhs`, leaving `rhs` in the - /// default-constructed state. Use the `waitOnDisconnect` state of - /// `rhs`, indicating whether `disconnect()` or `disconnectAndWait()` - /// will be called on the slot managed by this object upon destruction - /// or assignment. Return `*this`. Throws nothing. + /// `waitOnDisconnect` state. Make this connection refer to the same slot, + /// if any, as the specified `rhs`, leaving `rhs` in the + /// default-constructed state. Use the `waitOnDisconnect` state of `rhs`, + /// indicating whether `disconnect()` or `disconnectAndWait()` will be + /// called on the slot managed by this object upon destruction or + /// assignment. Return `*this`. Throws nothing. SignalerConnectionGuard& operator=(bslmf::MovableRef rhs) BSLS_KEYWORD_NOEXCEPT; @@ -1283,40 +1280,40 @@ class SignalerConnectionGuard { public: // ACCESSORS - /// Return a const reference to the connection held by this object. - /// Throws nothing. + /// Return a const reference to the connection held by this object. Throws + /// nothing. const SignalerConnection& connection() const BSLS_KEYWORD_NOEXCEPT; - /// Return a `bool` that indicates the value that determines whether - /// the slot, if any, managed by this object will be disconnected using + /// Return a `bool` that indicates the value that determines whether the + /// slot, if any, managed by this object will be disconnected using /// `disconnect` or `disconnectAndWait`. Throws nothing. bool waitOnDisconnect() const BSLS_KEYWORD_NOEXCEPT; }; // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` referring to the same -/// slot and `false` otherwise. +/// Return `true` if the specified `lhs` and `rhs` referring to the same slot +/// and `false` otherwise. bool operator==(const SignalerConnection& lhs, const SignalerConnection& rhs); -/// Return `false` if the specified `lhs` and `rhs` referring to the same -/// slot and `true` otherwise. +/// Return `false` if the specified `lhs` and `rhs` referring to the same slot +/// and `true` otherwise. bool operator!=(const SignalerConnection& lhs, const SignalerConnection& rhs); -/// Return `true` if the specified `lhs` is less than the specified `rhs` -/// and `false` otherwise. +/// Return `true` if the specified `lhs` is less than the specified `rhs` and +/// `false` otherwise. bool operator<(const SignalerConnection& lhs, const SignalerConnection& rhs); -/// Return `true` if the specified `lhs` is grater than the specified `rhs` -/// and `false` otherwise. +/// Return `true` if the specified `lhs` is grater than the specified `rhs` and +/// `false` otherwise. bool operator>(const SignalerConnection& lhs, const SignalerConnection& rhs); -/// Return `true` if the specified `lhs` is less than or equal to the -/// specified `rhs` and `false` otherwise. +/// Return `true` if the specified `lhs` is less than or equal to the specified +/// `rhs` and `false` otherwise. bool operator<=(const SignalerConnection& lhs, const SignalerConnection& rhs); diff --git a/groups/bsl/bslma/bslma_aatypeutil.h b/groups/bsl/bslma/bslma_aatypeutil.h index f8148b6f41..8525e3a905 100644 --- a/groups/bsl/bslma/bslma_aatypeutil.h +++ b/groups/bsl/bslma/bslma_aatypeutil.h @@ -25,6 +25,7 @@ BSLS_IDENT("$Id: $") // ///Usage ///----- +// This section illustrates intended use of this component. // ///Example 1: Constructing a New Member Using an Existing Member's Allocator ///- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -56,8 +57,8 @@ BSLS_IDENT("$Id: $") // int value() const { return d_value; } // }; // +// /// Another **legacy-AA** class. // class Curly { -// // Another **legacy-AA** class. // // // DATA // bslma::Allocator *d_allocator_p; @@ -84,13 +85,13 @@ BSLS_IDENT("$Id: $") // exists. Because the `Larry` member holds an allocator, there is no need for // a separate allocator data member: // ``` +// /// Holds a `Larry` object and possibly a `Curly` object. // class LarryMaybeCurly { -// // Holds a 'Larry' object and possibly a 'Curly' object. // // // DATA -// bool d_hasCurly; // True if 'd_curly' is populated +// bool d_hasCurly; // True if `d_curly` is populated // Larry d_larry; -// bsls::ObjectBuffer d_curly; // Maybe holds a 'Curly' object +// bsls::ObjectBuffer d_curly; // Maybe holds a `Curly` object // ``` // Next we complete the public interface, which includes a constructor that // sets the value of the `Larry` object, a manipulator for setting the value of @@ -104,17 +105,19 @@ BSLS_IDENT("$Id: $") // typedef bsl::allocator allocator_type; // // // CREATORS +// +// /// Create an object having a `Larry` member with the specified `v` +// /// value and having no `Curly` member. Optionally specify an +// /// allocator `a` to supply memory. // explicit LarryMaybeCurly(int v, // const allocator_type& a = allocator_type()); -// // Create an object having a 'Larry' member with the specified 'v' -// // value and having no 'Curly' member. Optionally specify an -// // allocator 'a' to supply memory. // // // ... // // // MANIPULATORS +// +// /// Initialize the `Curly` member to the specified `v` value. // void setCurly(int v); -// // initialize the 'Curly' member to the specified 'v' value. // // // ACCESSORS // bool hasCurly() const { return d_hasCurly; } diff --git a/groups/bsl/bslma/bslma_allocator.h b/groups/bsl/bslma/bslma_allocator.h index e2d4ba98ef..03b97cb6ae 100644 --- a/groups/bsl/bslma/bslma_allocator.h +++ b/groups/bsl/bslma/bslma_allocator.h @@ -151,7 +151,9 @@ BSLS_IDENT("$Id: $") // // private: // // PRIVATE MANIPULATORS -// void increaseSize(); // Increase the capacity by at least one element. +// +// /// Increase the capacity by at least one element. +// void increaseSize(); // // public: // // CREATORS @@ -410,15 +412,15 @@ class Allocator : public bsl::memory_resource { // PROTECTED MANIPULATORS /// Return a newly allocated block of memory of (at least) the specified - /// positive `bytes` and having at least the specified `alignment`. - /// Unless overriden in a derived class, the return value is - /// `this->allocate(bytes)`. If this allocator cannot return the - /// requested number of bytes or cannot satisfy the alignment request, - /// then it will throw a `std::bad_alloc` exception in an - /// exception-enabled build, or else will abort the program in a - /// non-exception build. The behavior is undefined unless '0 <= - /// bytes'. Unless overriden in a derived class, the behavior is - /// undefined if `alignment > bsls::AlignmentUtil::BSLS_MAX_ALIGNMENT`. + /// positive `bytes` and having at least the specified `alignment`. Unless + /// overriden in a derived class, the return value is + /// `this->allocate(bytes)`. If this allocator cannot return the requested + /// number of bytes or cannot satisfy the alignment request, then it will + /// throw a `std::bad_alloc` exception in an exception-enabled build, or + /// else will abort the program in a non-exception build. The behavior is + /// undefined unless '0 <= bytes'. Unless overriden in a derived class, + /// the behavior is undefined if `alignment > + /// bsls::AlignmentUtil::BSLS_MAX_ALIGNMENT`. void* do_allocate(std::size_t bytes, std::size_t alignment) BSLS_KEYWORD_OVERRIDE; @@ -435,8 +437,8 @@ class Allocator : public bsl::memory_resource { // PROTECTED ACCESSORS /// Return `true` if this allocator is equal to the specified `other` - /// allocator, meaning (at least) that a memory block allocated by one - /// can be deallocated by the other; otherwise return `false`. Unless + /// allocator, meaning (at least) that a memory block allocated by one can + /// be deallocated by the other; otherwise return `false`. Unless /// overriden, this method returns `this == &other`. bool do_is_equal(const memory_resource& other) const BSLS_KEYWORD_NOEXCEPT BSLS_KEYWORD_OVERRIDE; @@ -444,27 +446,27 @@ class Allocator : public bsl::memory_resource { public: // PUBLIC TYPES - /// Alias for an unsigned integral type capable of representing the - /// number of bytes in this platform's virtual address space. + /// Alias for an unsigned integral type capable of representing the number + /// of bytes in this platform's virtual address space. typedef std::size_t size_type; #ifndef BDE_OMIT_INTERNAL_DEPRECATED // CLASS METHODS - /// **DEPRECATED**: Use `bsls::BslExceptionUtil::throwBadAlloc` instead. - /// /// Throw `std::bad_alloc` if exceptions are enabled or abort the /// program otherwise. Derived classes and helper functions will /// typically call this function when they are unable to satisfy an /// allocation request. This function never returns. + /// + /// @DEPRECATED: Use `bsls::BslExceptionUtil::throwBadAlloc` instead. static void throwBadAlloc(); #endif // BDE_OMIT_INTERNAL_DEPRECATED // CREATORS /// Destroy this allocator. Note that the behavior of destroying an - /// allocator while memory is allocated from it is not specified; - /// unless you *know* that it is valid to do so, don't! + /// allocator while memory is allocated from it is not specified; unless + /// you *know* that it is valid to do so, don't! ~Allocator() BSLS_KEYWORD_OVERRIDE; // MANIPULATORS @@ -654,7 +656,7 @@ void Allocator::deleteObjectRaw(bsl::nullptr_t) } // close package namespace -#ifndef BDE_OPENSOURCE_PUBLICATION // BACKWARD_COMPATIBILITY +#ifndef BDE_OPENSOURCE_PUBLICATION // ============================================================================ // BACKWARD COMPATIBILITY // ============================================================================ @@ -665,7 +667,7 @@ typedef bslma::Allocator bslma_Allocator; #ifndef bdema_Allocator #define bdema_Allocator bslma::Allocator #endif -#endif // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY +#endif } // close enterprise namespace diff --git a/groups/bsl/bslma/bslma_allocatoradaptor.h b/groups/bsl/bslma/bslma_allocatoradaptor.h index fdf33c9119..f91142e377 100644 --- a/groups/bsl/bslma/bslma_allocatoradaptor.h +++ b/groups/bsl/bslma/bslma_allocatoradaptor.h @@ -7,9 +7,8 @@ BSLS_IDENT("$Id: $") //@PURPOSE: Provide a polymorphic adaptor for STL-style allocators // -//@CLASSES: AllocatorAdaptor -// -//@SEE_ALSO: +//@CLASSES: +// bslma::AllocatorAdaptor: polymorphic adaptor for STL allocators // //@DESCRIPTION: Within the BDE libraries, the prefered way to handle memory // allocation is through a pointer to the polymorphic base class, @@ -25,6 +24,10 @@ BSLS_IDENT("$Id: $") // ///Usage ///----- +// This section illustrates intended use of this component. +// +///Example 1: Basic Usage +/// - - - - - - - - - - - // Let's start with a simple class, `my::FilePath`, which allocates storage // using a `bslma::Allocator`: // ``` @@ -209,15 +212,15 @@ class AllocatorAdaptor_Imp : public Allocator { // MANIPULATORS - /// Return a maximally-aligned block of memory no smaller than `size` - /// bytes allocated from the STL-style allocator that was supplied to - /// this object's constructor. Any exceptions thrown by the underlying + /// Return a maximally-aligned block of memory no smaller than `size` bytes + /// allocated from the STL-style allocator that was supplied to this + /// object's constructor. Any exceptions thrown by the underlying /// STL-style allocator are propagated out from this member. void *allocate(size_type size) BSLS_KEYWORD_OVERRIDE; /// Return the memory block at the specified `address` back to the - /// STL-allocator. If `address` is null, this funciton has no effect. - /// The behavior is undefined unless `address` was allocated using this + /// STL-allocator. If `address` is null, this funciton has no effect. The + /// behavior is undefined unless `address` was allocated using this /// allocator object and has not already been deallocated. void deallocate(void *address) BSLS_KEYWORD_OVERRIDE; @@ -233,20 +236,19 @@ class AllocatorAdaptor_Imp : public Allocator { #ifdef BSLS_COMPILERFEATURES_SUPPORT_ALIAS_TEMPLATES /// Polymorphic wrapper around an STL-style allocator. Note that -/// `AllocatorAdaptor::Type` is the same type regardless of whether or -/// not the compiler supports alias templates. It should be used, -/// therefore, whenever the exact type of the adaptor is important. +/// `AllocatorAdaptor::Type` is the same type regardless of whether or not +/// the compiler supports alias templates. It should be used, therefore, +/// whenever the exact type of the adaptor is important. template using AllocatorAdaptor = AllocatorAdaptor_Imp::other>; #else -/// Polymorphic wrapper around an object of the specified `STL_ALLOC` -/// STL-style allocator template parameter. A pointer to an object of this -/// class can thus be used with any component that uses BDE-style memory -/// allocation. Note that `AllocatorAdaptor::Type` is the same type -/// regardless of whether or not the compiler supports alias templates. It -/// should be used, therefore, whenever the exact type of the adaptor is -/// important. +/// Polymorphic wrapper around an object of the specified `STL_ALLOC` STL-style +/// allocator template parameter. A pointer to an object of this class can +/// thus be used with any component that uses BDE-style memory allocation. +/// Note that `AllocatorAdaptor::Type` is the same type regardless of +/// whether or not the compiler supports alias templates. It should be used, +/// therefore, whenever the exact type of the adaptor is important. template class AllocatorAdaptor : public AllocatorAdaptor_Imp::other> @@ -263,12 +265,12 @@ class AllocatorAdaptor : public /// STL-style allocator. AllocatorAdaptor(); // = default - /// Constructs a polymorphic wrapper around a copy of the specified - /// 'stla' STL-style allocator. + /// Constructs a polymorphic wrapper around a copy of the specified 'stla' + /// STL-style allocator. AllocatorAdaptor(const STL_ALLOC& stla); - //! AllocatorAdaptor(const AllocatorAdaptor&); - //! ~AllocatorAdaptor(); + //! AllocatorAdaptor(const AllocatorAdaptor&) = default; + //! ~AllocatorAdaptor() = default; }; #endif // BSLS_COMPILERFEATURES_SUPPORT_ALIAS_TEMPLATES diff --git a/groups/bsl/bslma/bslma_allocatorutil.h b/groups/bsl/bslma/bslma_allocatorutil.h index c1bc919410..3f284406a0 100644 --- a/groups/bsl/bslma/bslma_allocatorutil.h +++ b/groups/bsl/bslma/bslma_allocatorutil.h @@ -27,6 +27,7 @@ BSLS_IDENT("$Id: $") // ///Usage ///----- +// This section illustrates intended use of this component. // ///Example 1: Future-proofing Member Construction /// - - - - - - - - - - - - - - - - - - - - - - - @@ -135,7 +136,7 @@ BSLS_IDENT("$Id: $") // ``` // ///Example 2: Building an AA object on the heap -///- - - - - - - - - - - - - - - - - - - - - - +/// - - - - - - - - - - - - - - - - - - - - - - // This example shows how we can allocate a *bsl-AA* object from an allocator // and construct the object, passing the allocator along, in one step. // @@ -433,9 +434,9 @@ struct AllocatorUtil { // PRIVATE TYPES - /// Metafunction derives from `true_type` if (template argument) - /// `t_ALLOC` is derived from any specialization of `bsl::allocator`; - /// else derives from `false_type`. + /// Metafunction derives from `true_type` if (template argument) `t_ALLOC` + /// is derived from any specialization of `bsl::allocator`; else derives + /// from `false_type`. template struct IsDerivedFromBslAllocator : bsl::integral_constant static typename bsl::enable_if< ! IsDerivedFromBslAllocator::value, @@ -459,43 +460,42 @@ struct AllocatorUtil { template static bslma::Allocator *adapt(const bsl::allocator& from); - /// Return a pointer to a block of raw memory allocated from the - /// specified `allocator` having the specified `nbytes` size and - /// optionally specified `alignment`. If `alignment` is larger than the - /// largest supported alignment, either the block will be aligned to the - /// maximum supported alignment or an exception will be thrown. The - /// specific choice of behavior is determined by the allocator: for - /// polymorphic allocators the behavior is determined by the memory - /// resource, whereas for non-polymorphic allocators, the alignment is - /// always truncated to the maximum non-extended alignment. + /// Return a pointer to a block of raw memory allocated from the specified + /// `allocator` having the specified `nbytes` size and optionally specified + /// `alignment`. If `alignment` is larger than the largest supported + /// alignment, either the block will be aligned to the maximum supported + /// alignment or an exception will be thrown. The specific choice of + /// behavior is determined by the allocator: for polymorphic allocators the + /// behavior is determined by the memory resource, whereas for + /// non-polymorphic allocators, the alignment is always truncated to the + /// maximum non-extended alignment. template static typename AllocatorUtil_Traits::void_pointer allocateBytes(const t_ALLOCATOR& allocator, std::size_t nbytes, std::size_t alignment = k_MAX_ALIGNMENT); - /// Return a pointer to a block of raw memory allocated from the - /// specified `allocator` having a size and alignment appropriate for an - /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` - /// for the number of objects; otherwise space for a single object is - /// allocated. Since `t_TYPE` cannot be deduced from the function - /// parameters, it must be supplied explicitly (in `<>` brackets) by the - /// caller. + /// Return a pointer to a block of raw memory allocated from the specified + /// `allocator` having a size and alignment appropriate for an object of + /// (templatize parameter) `t_TYPE`. Optionally specify `n` for the number + /// of objects; otherwise space for a single object is allocated. Since + /// `t_TYPE` cannot be deduced from the function parameters, it must be + /// supplied explicitly (in `<>` brackets) by the caller. template static typename AllocatorUtil_Traits::pointer allocateObject(const t_ALLOCATOR& allocator, std::size_t n = 1); - /// If the specified `allowed` tag is `bsl::true_type` assign the - /// allocator object at the specified `lhs` address the value of the - /// specified `rhs`; otherwise, do nothing, and, in both cases, return a - /// modifiable reference to `*lhs`. The `t_TYPE` template parameter is - /// typically an allocator type and the `allowed` flag is typically a - /// propagation trait dependant on the calling context, such as + /// If the specified `allowed` tag is `bsl::true_type` assign the allocator + /// object at the specified `lhs` address the value of the specified `rhs`; + /// otherwise, do nothing, and, in both cases, return a modifiable + /// reference to `*lhs`. The `t_TYPE` template parameter is typically an + /// allocator type and the `allowed` flag is typically a propagation trait + /// dependant on the calling context, such as /// `propagate_on_container_copy_assignment` or - /// `propagate_on_container_move_assignment`. Instantiation will fail - /// if `allowed` is `true_type` and `t_TYPE` lacks a publically - /// accessible copy assignment operator. The behavior is undefined - /// unless `allowed` is `true_type` or `*lhs == rhs` before the call. + /// `propagate_on_container_move_assignment`. Instantiation will fail if + /// `allowed` is `true_type` and `t_TYPE` lacks a publically accessible + /// copy assignment operator. The behavior is undefined unless `allowed` + /// is `true_type` or `*lhs == rhs` before the call. template static t_TYPE& assign(t_TYPE *lhs, const t_TYPE& rhs, @@ -505,11 +505,11 @@ struct AllocatorUtil { const t_TYPE& rhs, bsl::false_type allowed); - /// Return to the specified allocator the block raw memory at the - /// specified `p` address having the specified `nbytes` size and - /// optionally specified `alignment`. The behavior is undefined unless - /// `p` refers to a block having the same size and alignment previously - /// allocated from a copy of `allocator` and not yet deallocated. + /// Return to the specified allocator the block raw memory at the specified + /// `p` address having the specified `nbytes` size and optionally specified + /// `alignment`. The behavior is undefined unless `p` refers to a block + /// having the same size and alignment previously allocated from a copy of + /// `allocator` and not yet deallocated. template static void deallocateBytes( const t_ALLOCATOR& allocator, @@ -520,28 +520,28 @@ struct AllocatorUtil { /// Return to the specified `allocator` a block of raw memory at the /// specified `p` address that is suitably sized and aligned to hold an - /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` - /// for the number of objects; otherwise a single object is assumed. - /// The behavior is undefined unless `p` refers to a block with the same - /// type and number of objects previously allocated from a copy of - /// `allocator` and not yet deallocated. + /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` for + /// the number of objects; otherwise a single object is assumed. The + /// behavior is undefined unless `p` refers to a block with the same type + /// and number of objects previously allocated from a copy of `allocator` + /// and not yet deallocated. template static void deallocateObject(const t_ALLOCATOR& allocator, t_POINTER p, std::size_t n = 1); - /// Destroy the object at the specified `p` address and return the block - /// of memory at `p` to the specified `allocator`. The behavior is - /// undefined unless `p` refers to a fully constructed object allocated - /// from a copy of `allocator` and not yet destroyed or deallocated. + /// Destroy the object at the specified `p` address and return the block of + /// memory at `p` to the specified `allocator`. The behavior is undefined + /// unless `p` refers to a fully constructed object allocated from a copy + /// of `allocator` and not yet destroyed or deallocated. template static void deleteObject(const t_ALLOCATOR& allocator, t_POINTER p); /// Return an object of (template parameter) `t_TYPE` allocated from the /// specified `allocator` and constructed with no arguments except that, /// for scoped allocator types such as `bsl::allocator` and - /// `bsl::polymorphic_allocator`, `allocator` may be passed to the - /// `t_TYPE` constructor (i.e., if `t_TYPE` is AA). + /// `bsl::polymorphic_allocator`, `allocator` may be passed to the `t_TYPE` + /// constructor (i.e., if `t_TYPE` is AA). template static typename AllocatorUtil_Traits::pointer newObject(const t_ALLOCATOR& allocator); @@ -559,13 +559,12 @@ struct AllocatorUtil { /// Return an object of (template parameter) `t_TYPE` allocated from the /// specified `allocator` and constructed from the specified `argument1` /// and other specified `arguments`. For scoped allocator types such as - /// `bsl::allocator` and `bsl::polymorphic_allocator`, `allocator` may - /// be passed to the `t_TYPE` constructor as an additional argument - /// (i.e., if `t_TYPE` is AA). Note that, in C++03, perfect forwarding - /// is limited such that any lvalue reference in the `arguments` - /// parameter pack is const-qualified when forwarded to the - /// `TARGET_TYPE` constructor; only `argument1` can be forwarded as an - /// unqualified lvalue. + /// `bsl::allocator` and `bsl::polymorphic_allocator`, `allocator` may be + /// passed to the `t_TYPE` constructor as an additional argument (i.e., if + /// `t_TYPE` is AA). Note that, in C++03, perfect forwarding is limited + /// such that any lvalue reference in the `arguments` parameter pack is + /// const-qualified when forwarded to the `TARGET_TYPE` constructor; only + /// `argument1` can be forwarded as an unqualified lvalue. template static typename AllocatorUtil_Traits::pointer newObject(const t_ALLOCATOR& allocator, @@ -573,17 +572,16 @@ struct AllocatorUtil { t_ARGS&&... arguments); #endif - /// If the specified `allowed` tag is `bsl::true_type`, swap the values - /// of allocators at the specified `pa` and `pb` addresses using ADL - /// swap (with `std::swap` in scope); otherwise, do nothing. The - /// `t_TYPE` template parameter is typically an allocator type and the - /// `allowed` flag is typically a propagation trait dependant on the - /// calling context, such as `propagate_on_container_swap`. - /// Instantiation will fail if `allowed` is `false_type` and `t_TYPE` is - /// not swappable (i.e., because it lacks a publically available - /// assignment operator). The behavior is undefined unless `allowed` is - /// `true_type` or '*pa == - /// *pb' before the call. + /// If the specified `allowed` tag is `bsl::true_type`, swap the values of + /// allocators at the specified `pa` and `pb` addresses using ADL swap + /// (with `std::swap` in scope); otherwise, do nothing. The `t_TYPE` + /// template parameter is typically an allocator type and the `allowed` + /// flag is typically a propagation trait dependant on the calling context, + /// such as `propagate_on_container_swap`. Instantiation will fail if + /// `allowed` is `false_type` and `t_TYPE` is not swappable (i.e., because + /// it lacks a publically available assignment operator). The behavior is + /// undefined unless `allowed` is `true_type` or '*pa == *pb' before the + /// call. template static void swap(t_TYPE *pa, t_TYPE *pb, bsl::false_type allowed); template diff --git a/groups/bsl/bslma/bslma_allocatorutil_cpp03.h b/groups/bsl/bslma/bslma_allocatorutil_cpp03.h index 5a43730354..6c37efbb86 100644 --- a/groups/bsl/bslma/bslma_allocatorutil_cpp03.h +++ b/groups/bsl/bslma/bslma_allocatorutil_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 Sun Sep 1 05:38:38 2024 +// Generated on Fri Oct 4 16:23:48 2024 // Command line: sim_cpp11_features.pl bslma_allocatorutil.h #ifdef COMPILING_BSLMA_ALLOCATORUTIL_H @@ -113,9 +113,9 @@ struct AllocatorUtil { // PRIVATE TYPES - /// Metafunction derives from `true_type` if (template argument) - /// `t_ALLOC` is derived from any specialization of `bsl::allocator`; - /// else derives from `false_type`. + /// Metafunction derives from `true_type` if (template argument) `t_ALLOC` + /// is derived from any specialization of `bsl::allocator`; else derives + /// from `false_type`. template struct IsDerivedFromBslAllocator : bsl::integral_constant static typename bsl::enable_if< ! IsDerivedFromBslAllocator::value, @@ -139,43 +139,42 @@ struct AllocatorUtil { template static bslma::Allocator *adapt(const bsl::allocator& from); - /// Return a pointer to a block of raw memory allocated from the - /// specified `allocator` having the specified `nbytes` size and - /// optionally specified `alignment`. If `alignment` is larger than the - /// largest supported alignment, either the block will be aligned to the - /// maximum supported alignment or an exception will be thrown. The - /// specific choice of behavior is determined by the allocator: for - /// polymorphic allocators the behavior is determined by the memory - /// resource, whereas for non-polymorphic allocators, the alignment is - /// always truncated to the maximum non-extended alignment. + /// Return a pointer to a block of raw memory allocated from the specified + /// `allocator` having the specified `nbytes` size and optionally specified + /// `alignment`. If `alignment` is larger than the largest supported + /// alignment, either the block will be aligned to the maximum supported + /// alignment or an exception will be thrown. The specific choice of + /// behavior is determined by the allocator: for polymorphic allocators the + /// behavior is determined by the memory resource, whereas for + /// non-polymorphic allocators, the alignment is always truncated to the + /// maximum non-extended alignment. template static typename AllocatorUtil_Traits::void_pointer allocateBytes(const t_ALLOCATOR& allocator, std::size_t nbytes, std::size_t alignment = k_MAX_ALIGNMENT); - /// Return a pointer to a block of raw memory allocated from the - /// specified `allocator` having a size and alignment appropriate for an - /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` - /// for the number of objects; otherwise space for a single object is - /// allocated. Since `t_TYPE` cannot be deduced from the function - /// parameters, it must be supplied explicitly (in `<>` brackets) by the - /// caller. + /// Return a pointer to a block of raw memory allocated from the specified + /// `allocator` having a size and alignment appropriate for an object of + /// (templatize parameter) `t_TYPE`. Optionally specify `n` for the number + /// of objects; otherwise space for a single object is allocated. Since + /// `t_TYPE` cannot be deduced from the function parameters, it must be + /// supplied explicitly (in `<>` brackets) by the caller. template static typename AllocatorUtil_Traits::pointer allocateObject(const t_ALLOCATOR& allocator, std::size_t n = 1); - /// If the specified `allowed` tag is `bsl::true_type` assign the - /// allocator object at the specified `lhs` address the value of the - /// specified `rhs`; otherwise, do nothing, and, in both cases, return a - /// modifiable reference to `*lhs`. The `t_TYPE` template parameter is - /// typically an allocator type and the `allowed` flag is typically a - /// propagation trait dependant on the calling context, such as + /// If the specified `allowed` tag is `bsl::true_type` assign the allocator + /// object at the specified `lhs` address the value of the specified `rhs`; + /// otherwise, do nothing, and, in both cases, return a modifiable + /// reference to `*lhs`. The `t_TYPE` template parameter is typically an + /// allocator type and the `allowed` flag is typically a propagation trait + /// dependant on the calling context, such as /// `propagate_on_container_copy_assignment` or - /// `propagate_on_container_move_assignment`. Instantiation will fail - /// if `allowed` is `true_type` and `t_TYPE` lacks a publically - /// accessible copy assignment operator. The behavior is undefined - /// unless `allowed` is `true_type` or `*lhs == rhs` before the call. + /// `propagate_on_container_move_assignment`. Instantiation will fail if + /// `allowed` is `true_type` and `t_TYPE` lacks a publically accessible + /// copy assignment operator. The behavior is undefined unless `allowed` + /// is `true_type` or `*lhs == rhs` before the call. template static t_TYPE& assign(t_TYPE *lhs, const t_TYPE& rhs, @@ -185,11 +184,11 @@ struct AllocatorUtil { const t_TYPE& rhs, bsl::false_type allowed); - /// Return to the specified allocator the block raw memory at the - /// specified `p` address having the specified `nbytes` size and - /// optionally specified `alignment`. The behavior is undefined unless - /// `p` refers to a block having the same size and alignment previously - /// allocated from a copy of `allocator` and not yet deallocated. + /// Return to the specified allocator the block raw memory at the specified + /// `p` address having the specified `nbytes` size and optionally specified + /// `alignment`. The behavior is undefined unless `p` refers to a block + /// having the same size and alignment previously allocated from a copy of + /// `allocator` and not yet deallocated. template static void deallocateBytes( const t_ALLOCATOR& allocator, @@ -200,28 +199,28 @@ struct AllocatorUtil { /// Return to the specified `allocator` a block of raw memory at the /// specified `p` address that is suitably sized and aligned to hold an - /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` - /// for the number of objects; otherwise a single object is assumed. - /// The behavior is undefined unless `p` refers to a block with the same - /// type and number of objects previously allocated from a copy of - /// `allocator` and not yet deallocated. + /// object of (templatize parameter) `t_TYPE`. Optionally specify `n` for + /// the number of objects; otherwise a single object is assumed. The + /// behavior is undefined unless `p` refers to a block with the same type + /// and number of objects previously allocated from a copy of `allocator` + /// and not yet deallocated. template static void deallocateObject(const t_ALLOCATOR& allocator, t_POINTER p, std::size_t n = 1); - /// Destroy the object at the specified `p` address and return the block - /// of memory at `p` to the specified `allocator`. The behavior is - /// undefined unless `p` refers to a fully constructed object allocated - /// from a copy of `allocator` and not yet destroyed or deallocated. + /// Destroy the object at the specified `p` address and return the block of + /// memory at `p` to the specified `allocator`. The behavior is undefined + /// unless `p` refers to a fully constructed object allocated from a copy + /// of `allocator` and not yet destroyed or deallocated. template static void deleteObject(const t_ALLOCATOR& allocator, t_POINTER p); /// Return an object of (template parameter) `t_TYPE` allocated from the /// specified `allocator` and constructed with no arguments except that, /// for scoped allocator types such as `bsl::allocator` and - /// `bsl::polymorphic_allocator`, `allocator` may be passed to the - /// `t_TYPE` constructor (i.e., if `t_TYPE` is AA). + /// `bsl::polymorphic_allocator`, `allocator` may be passed to the `t_TYPE` + /// constructor (i.e., if `t_TYPE` is AA). template static typename AllocatorUtil_Traits::pointer newObject(const t_ALLOCATOR& allocator); @@ -791,17 +790,16 @@ struct AllocatorUtil { // }}} END GENERATED CODE #endif - /// If the specified `allowed` tag is `bsl::true_type`, swap the values - /// of allocators at the specified `pa` and `pb` addresses using ADL - /// swap (with `std::swap` in scope); otherwise, do nothing. The - /// `t_TYPE` template parameter is typically an allocator type and the - /// `allowed` flag is typically a propagation trait dependant on the - /// calling context, such as `propagate_on_container_swap`. - /// Instantiation will fail if `allowed` is `false_type` and `t_TYPE` is - /// not swappable (i.e., because it lacks a publically available - /// assignment operator). The behavior is undefined unless `allowed` is - /// `true_type` or '*pa == - /// *pb' before the call. + /// If the specified `allowed` tag is `bsl::true_type`, swap the values of + /// allocators at the specified `pa` and `pb` addresses using ADL swap + /// (with `std::swap` in scope); otherwise, do nothing. The `t_TYPE` + /// template parameter is typically an allocator type and the `allowed` + /// flag is typically a propagation trait dependant on the calling context, + /// such as `propagate_on_container_swap`. Instantiation will fail if + /// `allowed` is `false_type` and `t_TYPE` is not swappable (i.e., because + /// it lacks a publically available assignment operator). The behavior is + /// undefined unless `allowed` is `true_type` or '*pa == *pb' before the + /// call. template static void swap(t_TYPE *pa, t_TYPE *pb, bsl::false_type allowed); template diff --git a/groups/bsl/bslma/bslma_managedptrdeleter.h b/groups/bsl/bslma/bslma_managedptrdeleter.h index 3278677a7e..af8b213f7a 100644 --- a/groups/bsl/bslma/bslma_managedptrdeleter.h +++ b/groups/bsl/bslma/bslma_managedptrdeleter.h @@ -29,12 +29,16 @@ BSLS_IDENT("$Id$ $CSID$") // ------------------------------------------------------------------ // '0 == deleter' or 'deleter(object, factory)' has defined behavior. // ``` -// * object Address of the object to be destroyed by the factory. -// * factory Address of the factory object that is responsible for destroying -// `object`. -// * deleter Address of the function that restores the erased types of -// `object` and `factory`, and invokes the `factory` method to -// destroy `object`. +// * object +// > Address of the object to be destroyed by the factory. +// +// * factory +// > Address of the factory object that is responsible for destroying +// > `object`. +// +// * deleter +// > Address of the function that restores the erased types of `object` and +// > `factory`, and invokes the `factory` method to destroy `object`. #include @@ -49,16 +53,16 @@ namespace bslma { // class ManagedPtrDeleter // ======================= -/// This complex constrained in-core value-semantic class holds the -/// information necessary for `ManagedPtr` to correctly manage its -/// underlying object, namely the addresses of `object` and `factory`, and -/// the `deleter` function, optionally supplied through the constructors or -/// through the `set` method. This information is stored in a sub-structure -/// to allow the compiler to copy it more efficiently. +/// This complex constrained in-core value-semantic class holds the information +/// necessary for `ManagedPtr` to correctly manage its underlying object, +/// namely the addresses of `object` and `factory`, and the `deleter` function, +/// optionally supplied through the constructors or through the `set` method. +/// This information is stored in a sub-structure to allow the compiler to copy +/// it more efficiently. /// -/// See the {Attributes} section in the component-level documentation. Note -/// that the class invariants are identically the constraints on the -/// individual attributes. +/// See the [](#Attributes) for information on the class attributes. Note that +/// the class invariants are identically the constraints on the individual +/// attributes. /// /// This class: /// * supports a complete set of *value-semantic* operations @@ -86,25 +90,25 @@ class ManagedPtrDeleter { public: // CREATORS - /// Create a default `ManagedPtrDeleter` object that does not refer to - /// any object or factory instance. + /// Create a default `ManagedPtrDeleter` object that does not refer to any + /// object or factory instance. ManagedPtrDeleter(); /// Create a `ManagedPtrDeleter` object that refers to the object and /// factory instances located at the specified `object` and `factory` /// memory locations, and the specified `deleter`. The behavior is - /// undefined unless `deleter` is either 0, or points to a function - /// whose behavior is defined if called once with `object` and `factory` - /// as arguments. + /// undefined unless `deleter` is either 0, or points to a function whose + /// behavior is defined if called once with `object` and `factory` as + /// arguments. ManagedPtrDeleter(void *object, void *factory, Deleter deleter); /// Create a `ManagedPtrDeleter` object having the same value as the - /// specified `original` object. Note that this trivial copy - /// constructor's definition is compiler generated. + /// specified `original` object. Note that this trivial copy constructor's + /// definition is compiler generated. //! ManagedPtrDeleter(const ManagedPtrDeleter& original); - /// Destroy this object. Note that this trivial destructor's definition - /// is compiler generated. + /// Destroy this object. Note that this trivial destructor's definition is + /// compiler generated. //! ~ManagedPtrDeleter() = default; // MANIPULATORS @@ -121,22 +125,21 @@ class ManagedPtrDeleter { /// Set this `ManagedPtrDeleter` to refer to the object and factory /// instances located at the specified `object` and `factory` memory /// locations, and the specified `deleter`. The behavior is undefined - /// unless `deleter` is either 0, or points to a function whose behavior - /// is defined if called once with `object` and `factory` as arguments. + /// unless `deleter` is either 0, or points to a function whose behavior is + /// defined if called once with `object` and `factory` as arguments. void set(void *object, void *factory, Deleter deleter); // ACCESSORS - /// Invoke the deleter object. The behavior is undefined unless - /// `deleter` is not 0 and has not already been called on the managed - /// object associated with this deleter. + /// Invoke the deleter object. The behavior is undefined unless `deleter` + /// is not 0 and has not already been called on the managed object + /// associated with this deleter. void deleteManagedObject() const; /// Return the deleter function associated with this deleter. Deleter deleter() const; - /// Return a pointer to the factory instance associated with this - /// deleter. + /// Return a pointer to the factory instance associated with this deleter. void *factory() const; /// Return a pointer to the managed object associated with this deleter. @@ -145,16 +148,16 @@ class ManagedPtrDeleter { // FREE OPERATORS -/// Return `true` if the specified `lhs` and `rhs` objects have the same -/// value, and `false` otherwise. Two `ManagedPtrDeleter` objects have the -/// same value if the corresponding values of their `object`, `factory`, and -/// `deleter` attributes are the same. +/// Return `true` if the specified `lhs` and `rhs` objects have the same value, +/// and `false` otherwise. Two `ManagedPtrDeleter` objects have the same value +/// if the corresponding values of their `object`, `factory`, and `deleter` +/// attributes are the same. bool operator==(const ManagedPtrDeleter& lhs, const ManagedPtrDeleter& rhs); -/// Return `true` if the specified `lhs` and `rhs` objects do not have the -/// same value, and `false` otherwise. Two `ManagedPtrDeleter` objects do -/// not have the same value if any of the corresponding values of their -/// `object`, `factory`, and `deleter` attributes are not the same. +/// Return `true` if the specified `lhs` and `rhs` objects do not have the same +/// value, and `false` otherwise. Two `ManagedPtrDeleter` objects do not have +/// the same value if any of the corresponding values of their `object`, +/// `factory`, and `deleter` attributes are not the same. bool operator!=(const ManagedPtrDeleter& lhs, const ManagedPtrDeleter& rhs); // ============================================================================ diff --git a/groups/bsl/bslstl/bslstl_string.h b/groups/bsl/bslstl/bslstl_string.h index 8ba0269a1e..7644c6bc24 100644 --- a/groups/bsl/bslstl/bslstl_string.h +++ b/groups/bsl/bslstl/bslstl_string.h @@ -1799,6 +1799,7 @@ class basic_string /// a reference providing modifiable access to this string. basic_string& operator=(const basic_string& rhs); +#ifndef DOXYGEN_SKIP /// Assign to this string the value of the specified `rhs` string, /// propagate to this object the allocator of `rhs` if the `ALLOCATOR` /// type has trait `propagate_on_container_move_assignment`, and return @@ -1811,6 +1812,7 @@ class basic_string BSLS_KEYWORD_NOEXCEPT_SPECIFICATION( AllocatorTraits::propagate_on_container_move_assignment::value || AllocatorTraits::is_always_equal::value); +#endif /// Assign to this string the value of the specified `rhs` object, and /// return a reference providing modifiable access to this string. diff --git a/groups/bsl/bsltf/doc/bsltf.txt b/groups/bsl/bsltf/doc/bsltf.txt index 55e3355be1..ef16165ff1 100644 --- a/groups/bsl/bsltf/doc/bsltf.txt +++ b/groups/bsl/bsltf/doc/bsltf.txt @@ -8,7 +8,7 @@ operates on those types, which can help simplify, particularly for templates, the implementation of test drivers. - See {'bsltf_templatetestfacility'|DESCRIPTION} for an overview of the + See [](bsltf_templatetestfacility#DESCRIPTION) for an overview of the facilities in this package and examples of their use. /Hierarchical Synopsis