3) What is your evaluation of the documentation? ##################### Introduction section: ##################### The sentences in this section should all be folded into one paragraph. -- -- s/It provides allocation functions aligned_alloc and aligned_free as/ It provides the functions aligned_alloc and aligned_free as Rationale: aligned_free is not an allocation function. -- -- s/It provides C++ allocators, class templates aligned_allocator and aligned_allocator_adaptor, which respect alignment./It provides C++ allocators aligned_allocator and aligned_allocator_adaptor which respect alignment. s/The first uses aligned_alloc and aligned_free while the second uses the allocator in conjunction with align./The first uses aligned_alloc and aligned_free while the second uses a user specified allocator in conjunction with align. ################### Vocabulary section: ################### Can you indicate that this cites the C++11 standard? ######################## Interface documentation: ######################## The documentation of function semantics is inconsistent, at times it uses C++ Standards' notation, at other times it uses C Standards' notation. IMO, it should be normalized on C++ Standards' convention since Boost specifically targets C++ libraries. ###################### aligned_alloc section: ###################### Replace "Description" subsection with: Requires: The value of alignment shall be a power of two. Effects: The aligned_alloc function allocates space for an object whose alignment is specified by alignment, whose size is specified by size, and whose value is indeterminate. ##################### aligned_free section: ##################### Replace "Description" subsection with: Requires: ptr must be a value returned by aligned_alloc or a null pointer, and it must not have been used as parameter to some earlier call of aligned_free. Effects: The aligned_free function causes the space pointed to by ptr to be deallocated, that is, made available for further allocation. If ptr is a null pointer, no action occurs. ########################## aligned_allocator section: ########################## There are overloads of aligned_allocator::construct in the header file which are not accounted for in the documentation. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "aligned_allocator notes" section: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section should be moved under "aligned_allocator requirements", else it's easy to miss it. ######################### aligned_allocator_adaptor ########################## ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ aligned_allocator_adaptor requirements section: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The requirements on template paramter Allocator in C++03 should be documented, ie, it needs to define "rebind", "pointer", "size_type", since std::allocator_traits is absent from that standard, unless its decided that boost::container::allocator_traits will be used. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ aligned_allocator_adaptor constructors section: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section is missing the following C++03 variant: "explicit aligned_allocator_adaptor(const A& alloc)" ~~~~~~~~~~~~~~~~~~~~~~~~~~~ aligned_allocator_adaptor() ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Missing: Requires: Allocator type be default constructible. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ pointer allocate(size_type n) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following replacement for "Remarks" section is IMO much simpler and clearer: Remarks: The storage is obtained by calling A2::allocate on an object a2, where A2 is of type Allocate::rebind<some-unspecified-type>::other. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ pointer allocate(size_type n, const_void_pointer hint) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Same issues as "pointer allocate(size_type n)". Does the "Requires" section mean: aligned_allocator_adaptor<some-unspecified-type> a1; auto hint = a1.allocate(1); aligned_allocator_adaptor<some-type> a2; auto obj = a2.allocate(some-value, hint); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ void deallocate(pointer p, size_type n) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Same issues as "pointer allocate(size_type n)". ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ aligned_allocator_adaptor notes section: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section should be moved under "aligned_allocator_adaptor requirements", else it's easy to miss it. And can you document why (the Rationale) this adaptor can only return raw pointers. ################### is_aligned section: ################### Replace "Description" subsection with: Requires: alignment is a power of two. ptr is a valid address.