Re: [boost] [align] Review - Documentation Evaluation Part 1.

Subject: Re: [boost] [align] Review - Documentation Evaluation Part 1.
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2014-04-12 05:22:30

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.