Skip to content

Commit 83fbac4

Browse files
osubbooosubboo
committed
Fix documentation errors
1 parent 1c871b4 commit 83fbac4

File tree

10 files changed

+140
-141
lines changed

10 files changed

+140
-141
lines changed

‎groups/bal/balb/balb_leakybucket.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -222,7 +222,7 @@ BSLS_IDENT("$Id: $")
222222
// This section illustrates the intended use of this component.
223223
//
224224
///Example 1: Controlling Network Traffic Generation
225-
///-------------------------------------------------
225+
///- - - - - - - - - - - - - - - - - - - - - - - - -
226226
// In some systems, data is processed faster than they are consumed by I/O
227227
// interfaces. This could lead to data loss due to the overflowing of the
228228
// buffers where data is queued before being processed. In other systems,

‎groups/bal/balb/balb_ratelimiter.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ BSLS_IDENT("$Id: $")
169169
// This section illustrates the intended use of this component.
170170
//
171171
///Example 1: Controlling Network Traffic Generation
172-
///-------------------------------------------------
172+
///- - - - - - - - - - - - - - - - - - - - - - - - -
173173
// Suppose that we want to send data over a network interface with the load
174174
// spike limitations explained below:
175175
//

‎groups/bal/balb/balb_reservationguard.h

+4-4
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,15 @@ BSLS_IDENT("$Id: $")
3232
// This section illustrates the intended use of this component.
3333
//
3434
///Example 1: Guarding units reservation in operations with balb::LeakyBucket
35-
///--------------------------------------------------------------------------
35+
/// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3636
// Suppose that we are limiting the rate of network traffic generation using a
3737
// `balb::LeakyBucket` object. We send data buffer over a network interface
3838
// using the `mySendData` function:
3939
// ```
40+
// /// Send a specified 'dataSize' amount of data over the network. Return the
41+
// /// amount of data actually sent. Throw an exception if a network failure
42+
// /// is detected.
4043
// bsls::Types::Uint64 mySendData(size_t dataSize);
41-
// // Send a specified 'dataSize' amount of data over the network. Return
42-
// // the amount of data actually sent. Throw an exception if a network
43-
// // failure is detected.
4444
// ```
4545
// Notice that the `mySendData` function may throw an exception; therefore, we
4646
// should wait until `mySendData` returns before indicating the amount of data

‎groups/bdl/bdlb/bdlb_caselessstringviewhash.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ BSLS_IDENT("$Id: $")
2727
///-----
2828
// This section illustrates intended use of this component.
2929
//
30-
///Example 1: Basic Use of `bdlb::CaselessStringViewHash`:
30+
///Example 1: Basic Use of `bdlb::CaselessStringViewHash`
3131
/// - - - - - - - - - - - - - - - - - - - - - - - - - - -
3232
// Suppose we need an associative container to store, for any stock name, the
3333
// number of shares of that stock we own:

‎groups/bsl/bsla/doc/bsla.txt

+32-32
Original file line numberDiff line numberDiff line change
@@ -104,101 +104,101 @@
104104
This section provides a brief introduction to some of the components in the
105105
'bsla' package. See the documentation in each component for full details.
106106

107-
/'bsla_annotations'
108-
/ - - - - - - - - -
107+
/bsla_annotations
108+
/ - - - - - - - -
109109
This component exists to provide a single component whose header can be
110110
included to transitively include all of the annotation macros defined in the
111111
'bsla' package. The macros that are transitively included by this component
112112
correspond to various compiler features, and can be used to annotate code for
113113
specific compile-time safety checks.
114114

115-
/'bsla_deprecated'
116-
/ - - - - - - - -
115+
/bsla_deprecated
116+
/- - - - - - - -
117117
This component provides a preprocessor macro that hints to the compile that a
118118
function, variable, or type is deprecated.
119119

120-
/'bsla_error'
121-
/ - - - - - -
120+
/bsla_error
121+
/ - - - - -
122122
This component provides a preprocessor macro that flags a function such that a
123123
compiler error will occur when the function is called. On platforms where the
124124
appropriate attribute is not supported, the macro expands to nothing.
125125

126-
/'bsla_fallthrough'
127-
/- - - - - - - - -
126+
/bsla_fallthrough
127+
/ - - - - - - - -
128128
This component provides a preprocessor macro that suppresses compiler warnings
129129
about flow of control fall-through from one 'case' or 'default' of a 'switch'
130130
statement to another. On compilers where the appropriate attribute is not
131131
supported, the macro expands to nothing.
132132

133-
/'bsla_format'
134-
/ - - - - - -
133+
/bsla_format
134+
/- - - - - -
135135
This component provides a preprocessor macro to indicate that an indexed
136136
argument of a function is a 'printf'-style format specification, and that the
137137
function will return a 'printf'-style format string with an equivalent
138138
specification.
139139

140-
/'bsla_maybeunused'
141-
/- - - - - - - - -
140+
/bsla_maybeunused
141+
/ - - - - - - - -
142142
This component provides a preprocessor macro that will suppress "unused"
143143
warnings on a locally defined function, type, or variable that is not used.
144144

145-
/'bsla_nodiscard'
146-
/- - - - - - - -
145+
/bsla_nodiscard
146+
/ - - - - - - -
147147
This component provides a preprocessor macro that annotates a function such
148148
that a compiler warning will be generated if the return value of the function
149149
is ignored.
150150

151-
/'bsla_nonnullarg'
152-
/ - - - - - - - -
151+
/bsla_nonnullarg
152+
/- - - - - - - -
153153
This component provides preprocessor macros that define compiler-specific
154154
compile-time annotations. These macros instruct the compiler to warn if null
155155
is passed to certain arguments to a function, or, on platforms where the
156156
feature is not supported, expand to nothing.
157157

158-
/'bsla_noreturn'
159-
/ - - - - - - -
158+
/bsla_noreturn
159+
/- - - - - - -
160160
This component provides a preprocessor macro that annotates a function as
161161
never returning, resulting in a compiler warning if a path of control exists
162162
such that the function does return.
163163

164-
/'bsla_nullterminated'
165-
/ - - - - - - - - - -
164+
/bsla_nullterminated
165+
/- - - - - - - - - -
166166
This component provides preprocessor macros to indicate that a variadic
167167
function's arguments are terminated by a 'NULL' value, or, in the case of
168168
'BSLA_NULLTERMINATEDAT', by a 'NULL' value at a certain index. Note that the
169169
terminating 'NULL' must actually be 'NULL'; passing 0 in it's place will
170170
result in a warning.
171171

172-
/'bsla_printf'
173-
/- - - - - - -
172+
/bsla_printf
173+
/- - - - - -
174174
This component provides a preprocessor macro that allows the designation of a
175175
given function argument as a 'printf'-style format string, and arguments
176176
starting at a certain index in the argument list to be formatted according to
177177
that string.
178178

179-
/'bsla_scanf'
180-
/ - - - - - -
179+
/bsla_scanf
180+
/ - - - - -
181181
This component provides a preprocessor macro that indicates that one of the
182182
arguments to a function is a 'scanf'-style format string, and that the
183183
arguments starting at a certain index are to be checked for compatibility with
184184
that format string.
185185

186-
/'bsla_unreachable'
187-
/- - - - - - - - -
186+
/bsla_unreachable
187+
/ - - - - - - - -
188188
This component provides a preprocessor macro that hints to the compile that a
189189
statement in the code is intended to be unreachable.
190190

191-
/'bsla_unused'
192-
/ - - - - - -
191+
/bsla_unused
192+
/- - - - - -
193193
This component provides a preprocessor macro that will suppress "unused"
194194
warnings on a locally defined function, type, or variable that is not used.
195195

196-
/'bsla_used'
197-
/ - - - - -
196+
/bsla_used
197+
/- - - - -
198198
This component provides a preprocessor macro that will guarantee the emission
199199
of a local function, type, or variable whether it is used or not.
200200

201-
/'bsla_warning'
202-
/ - - - - - - -
201+
/bsla_warning
202+
/ - - - - - -
203203
This component provides a macro that indicates that a compiler warning should
204204
be emitted when a given function is called.

‎groups/bsl/bslfmt/bslfmt_format.h

+2-2
Original file line numberDiff line numberDiff line change
@@ -416,8 +416,8 @@ BSLS_IDENT("$Id: $")
416416
// bsl::string result = bsl::format("{:v}", date);
417417
// assert(bsl::string("23 October 1999") == result);
418418
//
419-
// result = bsl::format("{:N}", date);
420-
// assert(bsl::string("1999-10-23") == result);
419+
// result = bsl::format("{:N}", date);
420+
// assert(bsl::string("1999-10-23") == result);
421421
// ```
422422

423423
#include <bslscm_version.h>

‎groups/bsl/bslfmt/bslfmt_format_args.h

+2-2
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ BSLS_IDENT("$Id: $")
4040
///-----
4141
// In this section we show the intended use of this component.
4242
//
43-
///Example: 1 Create a `basic_format_args` object
44-
///- - - - - - - - - - - - - - - - - - - - - - - - -
43+
///Example: 1 Create a basic_format_args object
44+
/// - - - - - - - - - - - - - - - - - - - - - -
4545
// We do not expect most users of `bsl::format` to interact with this type
4646
// directly and instead use `bsl::format` or `bsl::vformat`. In addition,
4747
// there are only a very limited number of public methods so this example is

‎groups/bsl/bslfmt/package/bslfmt.mem

-1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,3 @@ bslfmt_mockformatcontext
2626
bslfmt_mockparsecontext
2727
bslfmt_standardformatspecification
2828
bslfmt_unicodecodepoint
29-

‎groups/bsl/bslh/doc/bslh.txt

+59-59
Original file line numberDiff line numberDiff line change
@@ -400,9 +400,9 @@
400400
hashing algorithm functor. All of the hashing algorithm functors in 'bslh'
401401
have the function signature shown below:
402402
..
403+
/// Incorporates the specified `data` of `length` bytes into the internal
404+
/// state of the hashing algorithm.
403405
void operator()(const char *data, size_t length);
404-
// Incorporates the specified 'data' of 'length' bytes into the internal
405-
// state of the hashing algorithm.
406406
..
407407
As we can see, the hashing algorithm functor takes a pointer to the start of
408408
the data and a length in bytes. To hash a C-String, we call the hashing
@@ -889,104 +889,104 @@
889889
/Component Overview
890890
/------------------
891891
This section provides a brief introduction to each of the components in the
892-
'bslh' package. Full details are available in the documentation of each
892+
`bslh` package. Full details are available in the documentation of each
893893
component.
894894

895-
/'bslh_defaulthashalgorithm'
896-
/- - - - - - - - - - - - - -
897-
The 'bslh_defaulthashalgorithm' component provides an unspecified default
895+
/bslh_defaulthashalgorithm
896+
/- - - - - - - - - - - - -
897+
The `bslh_defaulthashalgorithm` component provides an unspecified default
898898
hashing algorithm. The supplied algorithm is suitable for general purpose use
899899
in a hash table. The underlying algorithm is subject to change in future
900900
releases.
901901

902-
This class satisfies the requirements for regular 'bslh' hashing algorithms,
903-
as defined in 'bslh_hash'.
902+
This class satisfies the requirements for regular `bslh` hashing algorithms,
903+
as defined in `bslh_hash`.
904904

905-
/'bslh_defaultseededhashalgorithm'
906-
/- - - - - - - - - - - - - - - - -
907-
The 'bslh_defaultseededhashalgorithm' component provides an unspecified
905+
/bslh_defaultseededhashalgorithm
906+
/- - - - - - - - - - - - - - - -
907+
The `bslh_defaultseededhashalgorithm` component provides an unspecified
908908
default seeded hashing algorithm. The supplied algorithm is suitable for
909909
general purpose use in a hash table. The underlying algorithm is subject to
910910
change in future releases.
911911

912-
This class satisfies the requirements for seeded 'bslh' hashing algorithms, as
913-
defined in 'bslh_seededhash'.
912+
This class satisfies the requirements for seeded `bslh` hashing algorithms, as
913+
defined in `bslh_seededhash`.
914914

915-
/'bslh_hash'
916-
/- - - - - -
917-
The {'bslh_hash'} component provides a templated 'struct', 'bslh::Hash', which
915+
/bslh_hash
916+
/- - - - -
917+
The `bslh_hash` component provides a templated `struct`, `bslh::Hash`, which
918918
provides hashing functionality. This struct is a drop in replacement for
919-
'bsl::hash'. 'bslh::Hash' is a wrapper that adapts hashing algorithms from
920-
'bslh' and 'hashAppend' free functions to match the interface of 'bsl::hash'.
921-
This component also contains 'hashAppend' definitions for fundamental types,
922-
which are required to make the hashing algorithms in 'bslh' work.
923-
924-
/'bslh_seededhash'
925-
/- - - - - - - - -
926-
The {'bslh_seededhash'} component provides a templated struct,
927-
'bslh::SeededHash', which provides hashing functionality. This 'struct' is a
928-
drop in replacement for 'bsl::hash'. It is similar to 'bslh::Hash', however,
919+
`bsl::hash`. `bslh::Hash` is a wrapper that adapts hashing algorithms from
920+
`bslh` and `hashAppend` free functions to match the interface of `bsl::hash`.
921+
This component also contains `hashAppend` definitions for fundamental types,
922+
which are required to make the hashing algorithms in `bslh` work.
923+
924+
/bslh_seededhash
925+
/- - - - - - - -
926+
The `bslh_seededhash` component provides a templated struct,
927+
`bslh::SeededHash`, which provides hashing functionality. This `struct` is a
928+
drop in replacement for `bsl::hash`. It is similar to `bslh::Hash`, however,
929929
it is meant for hashes that require a seed. It takes a seed generator and
930-
uses that to create seeds to give the hashing algorithm. 'bslh::SeededHash'
931-
is a wrapper which adapts hashing algorithms from 'bslh' to match the
932-
interface of 'bsl::hash'. 'bslh::SeededHash' is a universal hashing functor
933-
that will hash any type that implements 'hashAppend' using the hashing
930+
uses that to create seeds to give the hashing algorithm. `bslh::SeededHash`
931+
is a wrapper which adapts hashing algorithms from `bslh` to match the
932+
interface of `bsl::hash`. `bslh::SeededHash` is a universal hashing functor
933+
that will hash any type that implements `hashAppend` using the hashing
934934
algorithm provided as a template parameter.
935935

936-
/'bslh_seedgenerator'
937-
/ - - - - - - - - - -
938-
The {'bslh_seedgenerator'} component provides a class, 'bslh::SeedGenerator',
936+
/bslh_seedgenerator
937+
/ - - - - - - - - -
938+
The `bslh_seedgenerator` component provides a class, `bslh::SeedGenerator`,
939939
which utilizes a user-supplied random number generator (RNG) to generate
940940
arbitrary length seeds. The quality of the seeds will only be as good as the
941941
quality of the supplied RNG. A cryptographically secure RNG must be supplied
942-
in order for 'SeedGenerator' to produce seeds suitable for a cryptographically
942+
in order for `SeedGenerator` to produce seeds suitable for a cryptographically
943943
secure algorithm.
944944

945945
This class satisfies the requirements for a seed generator, as defined in
946-
'bslh_seededhash'.
946+
`bslh_seededhash`.
947947

948-
/'bslh_siphashalgorithm'
949-
/- - - - - - - - - - - -
950-
The 'bslh_siphashalgorithm' component provides an implementation of the
948+
/bslh_siphashalgorithm
949+
/- - - - - - - - - - -
950+
The `bslh_siphashalgorithm` component provides an implementation of the
951951
SipHash algorithm. SipHash is an algorithm designed for speed and security.
952952
A primary use case for this algorithm is to provide an extra line of defense
953-
in hash tables (such as the underlying implementation of 'unordered_map')
953+
in hash tables (such as the underlying implementation of `unordered_map`)
954954
against malicious input that could cause Denial of Service (DoS) attacks. It
955955
is based on one of the finalists for the SHA-3 cryptographic hash standard.
956956
Full details of the hash function can be found here:
957-
'{https://131002.net/siphash/siphash.pdf}'. This particular implementation
958-
has been derived from 'siphash.h' in Howard Hinnant's work here:
959-
'{https://github.com/HowardHinnant/hash_append}' and as much of the original
957+
https://131002.net/siphash/siphash.pdf. This particular implementation
958+
has been derived from `siphash.h` in Howard Hinnant's work here:
959+
https://github.com/HowardHinnant/hash_append and as much of the original
960960
code as possible, including comment headers, has been preserved.
961961

962-
This class satisfies the requirements for seeded 'bslh' hashing algorithms, as
963-
defined in 'bslh_seededhash'.
962+
This class satisfies the requirements for seeded `bslh` hashing algorithms, as
963+
defined in `bslh_seededhash`.
964964

965-
/'bslh_spookyhashalgorithm'
966-
/ - - - - - - - - - - - - -
967-
The 'bslh_spookyhashalgorithm' component provides an implementation of the
965+
/bslh_spookyhashalgorithm
966+
/ - - - - - - - - - - - -
967+
The `bslh_spookyhashalgorithm` component provides an implementation of the
968968
SpookyHash algorithm by Bob Jenkins. This algorithm is a general purpose
969969
algorithm that is known to quickly reach good avalanche performance and
970970
execute in time that is comparable to or faster than other industry standard
971971
algorithms such as CityHash. It is a good default choice for hashing values
972972
in unordered associative containers. For more information, see
973-
'http://burtleburtle.net/bob/hash/spooky.html'.
973+
http://burtleburtle.net/bob/hash/spooky.html.
974974

975-
This class satisfies the requirements for regular 'bslh' hashing algorithms
976-
and seeded 'bslh' hashing algorithms, as defined in 'bslh_hash' and
977-
'bslh_seededhash' respectively.
975+
This class satisfies the requirements for regular `bslh` hashing algorithms
976+
and seeded `bslh` hashing algorithms, as defined in `bslh_hash` and
977+
`bslh_seededhash` respectively.
978978

979-
/'bslh_spookyhashalgorithmimp'
980-
/- - - - - - - - - - - - - - -
981-
The 'bslh_spookyhashalgorithmimp' component provides BDE-style encapsulation
979+
/bslh_spookyhashalgorithmimp
980+
/- - - - - - - - - - - - - -
981+
The `bslh_spookyhashalgorithmimp` component provides BDE-style encapsulation
982982
of Bob Jenkins canonical SpookyHash implementation. SpookyHash provides a way
983983
to hash contiguous data all at once, or non-contiguous data in pieces. More
984-
information is available at 'http://burtleburtle.net/bob/hash/spooky.html'.
984+
information is available at http://burtleburtle.net/bob/hash/spooky.html.
985985

986-
/'bslh_wyhashincrementalalgorithm'
987-
/- - - - - - - - - - - - - - - - -
988-
The 'WyHash' algorithm, 'wyhash_final_version_3' with the 'incremental'
986+
/bslh_wyhashincrementalalgorithm
987+
/- - - - - - - - - - - - - - - -
988+
The `WyHash` algorithm, `wyhash_final_version_3` with the `incremental`
989989
property added, meaning that hashing a segment in a single pass will yield the
990990
same result as hashing it in contiguous pieces, but, unlike the original
991-
'WyHash', this algorithm yields different results depending on the byte order
991+
`WyHash`, this algorithm yields different results depending on the byte order
992992
of the host.

0 commit comments

Comments
 (0)