Skip to content

Commit

Permalink
Documentation style fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@osubboo
osubboo committed Feb 13, 2025
1 parent b63e85a commit 5a43e3d
Show file tree
Hide file tree
Showing 7 changed files with 173 additions and 157 deletions.
74 changes: 38 additions & 36 deletions groups/bdl/bdlma/bdlma_alignedallocator.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,12 @@ BSLS_IDENT("$Id$")
// // myposixmemalignallocator.h
// // ...
//
// /// This class is a sample concrete implementation of the
// /// `bdlma::AlignedAllocator` protocol that provides direct access to
// /// the system-supplied `posix_memalign` and `free` on Linux and AIX
// /// platforms, `memalign` and `free` on SunOS, or `_aligned_malloc` and
// /// `_aligned_free` on Windows.
// class MyAlignedAllocator: public bdlma::AlignedAllocator {
// // This class is a sample concrete implementation of the
// // 'bdlma::AlignedAllocator' protocol that provides direct access to
// // the system-supplied 'posix_memalign' and 'free' on Linux and AIX
// // platforms, 'memalign' and 'free' on SunOS, or '_aligned_malloc' and
// // '_aligned_free' on Windows.
//
// private:
// // NOT IMPLEMENTED
Expand All @@ -69,47 +69,49 @@ BSLS_IDENT("$Id$")
//
// public:
// // CREATORS
//
// /// Create a `MyAlignedAllocator` object. Note that all objects of
// /// this class share the same underlying resource.
// MyAlignedAllocator();
// // Create a 'MyAlignedAllocator' object. Note that all objects of
// // this class share the same underlying resource.
//
// /// Destroy this object. Note that destroying this object has no
// /// effect on any outstanding allocated memory.
// virtual ~MyAlignedAllocator();
// // Destroy this object. Note that destroying this object has no
// // effect on any outstanding allocated memory.
//
// // MANIPULATORS
//
// /// Return a newly allocated block of memory of (at least) the
// /// specified positive `size` (in bytes). If `size` is 0, a null
// /// pointer is returned with no other effect. If this allocator
// /// cannot return the requested number of bytes, then it will throw
// /// an `std::bad_alloc` exception in an exception-enabled build, or
// /// else it will abort the program in a non-exception build. The
// /// behavior is undefined unless `0 <= size`. Note that the
// /// alignment of the address returned conforms to the platform
// /// requirement for any object of the `size`. Also note that global
// /// `operator new` is *not* called when `size` is 0 (in order to
// /// avoid having to acquire a lock, and potential contention in
// /// multi-threaded programs).
// virtual void *allocate(bsls::Types::size_type size);
// // Return a newly allocated block of memory of (at least) the
// // specified positive 'size' (in bytes). If 'size' is 0, a null
// // pointer is returned with no other effect. If this allocator
// // cannot return the requested number of bytes, then it will throw
// // an 'std::bad_alloc' exception in an exception-enabled build, or
// // else it will abort the program in a non-exception build. The
// // behavior is undefined unless '0 <= size'. Note that the
// // alignment of the address returned conforms to the platform
// // requirement for any object of the 'size'. Also note that global
// // 'operator new' is *not* called when 'size' is 0 (in order to
// // avoid having to acquire a lock, and potential contention in
// // multi-threaded programs).
//
// /// Return the address of a newly allocated block of memory of at
// /// least the specified positive `size` (in bytes), sufficiently
// /// aligned such that the returned `address` satisfies, for the
// /// specified `alignment`, `0 == (address & (alignment - 1))`. If
// /// `size` is 0, a null pointer is returned with no other effect.
// /// If the requested number of appropriately aligned bytes cannot be
// /// returned, then a `bsl::bad_alloc` exception is thrown, or in a
// /// non-exception build the program is terminated. The behavior is
// /// undefined unless `alignment` is both a multiple of
// /// `sizeof(void *)` and an integral non-negative power of two.
// virtual void *allocateAligned(bsls::Types::size_type size,
// bsls::Types::size_type alignment);
// // Return the address of a newly allocated block of memory of at
// // least the specified positive 'size' (in bytes), sufficiently
// // aligned such that the returned 'address' satisfies, for the
// // specified 'alignment', '0 == (address & (alignment - 1))'. If
// // 'size' is 0, a null pointer is returned with no other effect.
// // If the requested number of appropriately aligned bytes cannot be
// // returned, then a 'bsl::bad_alloc' exception is thrown, or in a
// // non-exception build the program is terminated. The behavior is
// // undefined unless 'alignment' is both a multiple of
// // 'sizeof(void *)' and an integral non-negative power of two.
//
// /// Return the memory block at the specified `address` back to this
// /// allocator. If `address` is 0, this function has no effect. The
// /// behavior is undefined unless `address` was allocated using this
// /// allocator object and has not already been deallocated.
// virtual void deallocate(void *address);
// // Return the memory block at the specified 'address' back to this
// // allocator. If 'address' is 0, this function has no effect. The
// // behavior is undefined unless 'address' was allocated using this
// // allocator object and has not already been deallocated.
// };
// // ...
// ```
Expand Down Expand Up @@ -152,7 +154,7 @@ BSLS_IDENT("$Id$")
//
// void *ret = 0;
//
// #ifdef BSLS_PLATFORM_OS_WINDOWS
// #if defined(BSLS_PLATFORM_OS_WINDOWS)
// errno = 0;
// ret = _aligned_malloc(size, alignment);
// if (0 != errno) {
Expand Down
14 changes: 7 additions & 7 deletions groups/bdl/bdlma/bdlma_aligningallocator.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,18 +61,18 @@ BSLS_IDENT("$Id$")
// First, the externally supplied library defines the `struct` describing a
// node in the linked list:
// ```
// /// This `struct` describes one node in a linked list containing strings.
// struct Node {
// // This 'struct' describes one node in a linked list containing
// // strings.
//
// Node *d_next;
// char d_string[1];
//
// // CLASS METHODS
//
// /// Return the size in bytes needed to store a `Node` containing a
// /// copy of the specified `string`.
// static
// bsl::size_t sizeNeededForString(const char *string)
// // Return the size in bytes needed to store a 'Node' containing a
// // copy of the specified 'string'.
// {
// Node node;
//
Expand All @@ -84,12 +84,12 @@ BSLS_IDENT("$Id$")
// the linked list of nodes from a null-terminated array of pointers to
// C-strings:
// ```
// /// Create a linked list of strings beginning with the specified `*head`
// /// containing the null-terminated strings from the null-terminated
// /// `stringArray`. Use the specified `allocator` to supply memory.
// void externalPopulateStringList(Node **head,
// const char **stringArray,
// bslma::Allocator *allocator)
// // Create a linked list of strings beginning with the specified '*head'
// // containing the null-terminated strings from the null-terminated
// // 'stringArray'. Use the specified 'allocator' to supply memory.
// {
// *head = 0;
// const char *string;
Expand Down
45 changes: 22 additions & 23 deletions groups/bdl/bdlma/bdlma_autoreleaser.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,10 @@ BSLS_IDENT("$Id: $")
//
// First, we define the interface of our `my_FastStrArray` class:
// ```
// /// This class implements an array of C string elements. Each C string
// /// is allocated using the 'my_StrPool' member for fast memory
// /// allocation and deallocation.
// class my_FastCstrArray {
// // This class implements an array of C string elements. Each C string
// // is allocated using the 'my_StrPool' member for fast memory
// // allocation and deallocation.
//
// // DATA
// char **d_array_p; // dynamically allocated array
Expand Down Expand Up @@ -103,18 +103,18 @@ BSLS_IDENT("$Id: $")
// return size * k_MY_GROW_FACTOR;
// }
//
// /// Reallocate memory in the specified `array` and update the specified
// /// `size` to the specified `newSize`, using the specified `allocator`
// /// to supply memory. The specified `length` number of leading elements
// /// are preserved. If `allocate` should throw an exception, this
// /// function has no effect. The behavior is undefined unless
// /// `1 <= newSize`, `0 <= length`, and `length <= newSize`.
// static inline
// void reallocate(char ***array,
// int *size,
// int newSize,
// int length,
// bslma::Allocator *allocator)
// // Reallocate memory in the specified 'array' and update the specified
// // 'size' to the specified 'newSize', using the specified 'allocator'
// // to supply memory. The specified 'length' number of leading elements
// // are preserved. If 'allocate' should throw an exception, this
// // function has no effect. The behavior is undefined unless
// // '1 <= newSize', '0 <= length', and 'length <= newSize'.
// {
// ASSERT(array);
// ASSERT(*array);
Expand Down Expand Up @@ -255,28 +255,27 @@ class AutoReleaser {
// CREATORS

/// Create a proctor object to manage the specified `originalAllocator`.
/// Unless the `release` method of this proctor is invoked, the
/// `release` method of `originalAllocator` is automatically invoked
/// upon destruction of this proctor.
/// Unless the `release` method of this proctor is invoked, the `release`
/// method of `originalAllocator` is automatically invoked upon destruction
/// of this proctor.
AutoReleaser(ALLOCATOR *originalAllocator);

/// Destroy this proctor object and, unless the `release` method has
/// been invoked on this object with no subsequent call to `reset`,
/// invoke the `release` method of the held allocator or pool.
/// Destroy this proctor object and, unless the `release` method has been
/// invoked on this object with no subsequent call to `reset`, invoke the
/// `release` method of the held allocator or pool.
~AutoReleaser();

// MANIPULATORS

/// Release from management the allocator or pool currently managed by
/// this proctor. If no allocator or pool is currently being managed,
/// this method has no effect.
/// Release from management the allocator or pool currently managed by this
/// proctor. If no allocator or pool is currently being managed, this
/// method has no effect.
void release();

/// Set the specified `newAllocator` as the allocator or pool to be
/// managed by this proctor. Note that this method releases from
/// management any previously held allocator or pool, and so may be
/// invoked with or without having called `release` when reusing this
/// object.
/// Set the specified `newAllocator` as the allocator or pool to be managed
/// by this proctor. Note that this method releases from management any
/// previously held allocator or pool, and so may be invoked with or
/// without having called `release` when reusing this object.
void reset(ALLOCATOR *newAllocator);
};

Expand Down
25 changes: 14 additions & 11 deletions groups/bdl/bdlma/bdlma_blocklist.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,12 @@ BSLS_IDENT("$Id: $")
//
// private:
// // PRIVATE MANIPULATORS
//
// /// Request a new memory block of at least the specified `numBytes`
// /// size and allocate the initial `numBytes` from this block.
// /// Return the address of the allocated memory. The behavior is
// /// undefined unless `0 < numBytes`.
// void *allocateBlock(bsls::Types::size_type numBytes);
// // Request a new memory block of at least the specified 'numBytes'
// // size and allocate the initial 'numBytes' from this block.
// // Return the address of the allocated memory. The behavior is
// // undefined unless '0 < numBytes'.
//
// private:
// // NOT IMPLEMENTED
Expand All @@ -64,21 +65,23 @@ BSLS_IDENT("$Id: $")
//
// public:
// // CREATORS
//
// /// Create a memory manager. Optionally specify a `basicAllocator`
// /// used to supply memory. If `basicAllocator` is 0, the currently
// /// installed default allocator is used.
// my_StrPool(bslma::Allocator *basicAllocator = 0);
// // Create a memory manager. Optionally specify a 'basicAllocator'
// // used to supply memory. If 'basicAllocator' is 0, the currently
// // installed default allocator is used.
//
// /// Destroy this object and release all associated memory.
// ~my_StrPool();
// // Destroy this object and release all associated memory.
//
// // MANIPULATORS
//
// /// Allocate the specified `numBytes` of memory and return its
// /// address. If `numBytes` is 0, return 0 with no other effect.
// void *allocate(bsls::Types::size_type numBytes);
// // Allocate the specified 'numBytes' of memory and return its
// // address. If 'numBytes' is 0, return 0 with no other effect.
//
// /// Release all memory currently allocated through this object.
// void release();
// // Release all memory currently allocated through this object.
// };
//
// // MANIPULATORS
Expand Down
Loading

0 comments on commit 5a43e3d

Please sign in to comment.