[Boost-commit] svn:boost r76102 - trunk/boost

Subject: [Boost-commit] svn:boost r76102 - trunk/boost
From: dwalker07_at_[hidden]
Date: 2011-12-22 06:51:50

Author: dlwalker
Date: 2011-12-22 06:51:49 EST (Thu, 22 Dec 2011)
New Revision: 76102
URL: http://svn.boost.org/trac/boost/changeset/76102

Log:
Added Doxygen comments; marked some example CRC computer types as not matching their supposed standard.
Text files modified: 
   trunk/boost/crc.hpp |   494 +++++++++++++++++++++++++++++++++++++++ 
   1 files changed, 492 insertions(+), 2 deletions(-)

Modified: trunk/boost/crc.hpp
==============================================================================
--- trunk/boost/crc.hpp	(original)
+++ trunk/boost/crc.hpp	2011-12-22 06:51:49 EST (Thu, 22 Dec 2011)
@@ -7,6 +7,27 @@
 
 //  See <http://www.boost.org/libs/crc/> for the library's home page.
 
+/** \file
+    \brief  A collection of function templates and class templates that compute
+      various forms of Cyclic Redundancy Codes (CRCs).
+
+    \author  Daryle Walker
+
+    \version  1.5
+
+    \copyright  Boost Software License, version 1.0
+
+    Contains the declarations (and definitions) of various kinds of CRC
+    computation functions, function object types, and encapsulated policy types.
+
+    \note  There are references to the <i>Rocksoft&trade; Model CRC
+      Algorithm</i>, as described within \"<cite>A Painless Guide to CRC Error
+      Detection Algorithms</cite>,\" linked from \"<a
+      href="http://www.ross.net/crc/crcpaper.html">CRC: A Paper On CRCs</a>\" by
+      Ross Williams.  It will be abbreviated \"RMCA\" in other documentation
+      blocks.
+ */
+
 #ifndef BOOST_CRC_HPP
 #define BOOST_CRC_HPP
 
@@ -68,15 +89,18 @@
 
 //  Forward declarations  ----------------------------------------------------//
 
+//! Bit-wise CRC computer
 template < std::size_t Bits >
     class crc_basic;
 
+//! Table-driven CRC computer, usable as a function object
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly = 0u,
            BOOST_CRC_PARM_TYPE InitRem = 0u,
            BOOST_CRC_PARM_TYPE FinalXor = 0u, bool ReflectIn = false,
            bool ReflectRem = false >
     class crc_optimal;
 
+//! Compute the (unaugmented) CRC of a memory block
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -84,15 +108,21 @@
      std::size_t byte_count
      BOOST_CRC_DUMMY_PARM_TYPE );
 
+//! Compute the CRC of a memory block, with any augmentation provided by user
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly >
     typename uint_t<Bits>::fast  augmented_crc( void const *buffer,
      std::size_t byte_count, typename uint_t<Bits>::fast initial_remainder = 0u
      BOOST_ACRC_DUMMY_PARM_TYPE );
 
+//! Computation type for ARC|CRC-16|CRC-IBM|CRC-16/ARC|CRC-16/LHA standard
 typedef crc_optimal<16, 0x8005, 0, 0, true, true>         crc_16_type;
+//! Computation type for an incorrectly marked standard(!!)
 typedef crc_optimal<16, 0x1021, 0xFFFF, 0, false, false>  crc_ccitt_type;
+//! Computation type that I mistakenly called the XMODEM standard; it inverts
+//! both reflection parameters and reflects the truncated divisor (Don't use?!)
 typedef crc_optimal<16, 0x8408, 0, 0, true, true>         crc_xmodem_type;
 
+//! Computation type for CRC-32|CRC-32/ADCCP|PKZIP standard
 typedef crc_optimal<32, 0x04C11DB7, 0xFFFFFFFF, 0xFFFFFFFF, true, true>
   crc_32_type;
 
@@ -100,6 +130,7 @@
 //  Forward declarations for implementation detail stuff  --------------------//
 //  (Just for the stuff that will be needed for the next two sections)
 
+//! \cond
 namespace detail
 {
     template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly, bool Reflect >
@@ -114,43 +145,77 @@
     #endif
 
 }  // namespace detail
+//! \endcond
 
 
 //  Simple cyclic redundancy code (CRC) class declaration  -------------------//
 
+/** Objects of this type compute the CRC checksum of submitted data, where said
+    data can be entered piecemeal through several different kinds of groupings.
+    Modulo-2 polynomial division steps are always performed bit-wise, without
+    the use of pre-computation tables.  Said division uses the altered
+    algorithm, so any data has to be unaugmented.
+
+    \pre  0 \< \a Bits \<= \c std::numeric_limits&lt;uintmax_t&gt;::digits
+
+    \tparam Bits  The order of the modulo-2 polynomial divisor.  (\e Width from
+      the RMCA)
+ */
 template < std::size_t Bits >
 class crc_basic
 {
 public:
     // Type
+    /** \brief  The register type used for computations
+
+        This type is used for CRC calculations and is the type for any returned
+        checksums and returned or submitted remainders, (truncated) divisors, or
+        XOR masks.  It is a built-in unsigned integer type.
+     */
     typedef typename boost::uint_t<Bits>::fast  value_type;
 
     // Constant for the template parameter
+    //! A copy of \a Bits provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( std::size_t, bit_count = Bits );
 
-    // Constructor
+    // Constructor (use the automatic copy-ctr, move-ctr, and dtr)
+    //! Create a computer, separately listing each needed parameter
     explicit  crc_basic( value_type truncated_polynominal,
                value_type initial_remainder = 0, value_type final_xor_value = 0,
                bool reflect_input = false, bool reflect_remainder = false );
 
     // Internal Operations
+    //! Return the (truncated) polynomial divisor
     value_type  get_truncated_polynominal() const;
+    //! Return what the polynomial remainder was set to during construction
     value_type  get_initial_remainder() const;
+    //! Return the XOR-mask used during output processing
     value_type  get_final_xor_value() const;
+    //! Check if input-bytes will be reflected before processing
     bool        get_reflect_input() const;
+    //! Check if the remainder will be reflected during output processing
     bool        get_reflect_remainder() const;
 
+    //! Return the remainder based from already-processed bits
     value_type  get_interim_remainder() const;
+    //! Change the interim remainder to a new value
     void        reset( value_type new_rem );
+    //! Change the interim remainder back to the initial value
     void        reset();
 
     // External Operations
+    //! Submit a single bit for input processing
     void  process_bit( bool bit );
+    //! Submit the lowest \a bit_count bits of a byte for input processing
     void  process_bits( unsigned char bits, std::size_t bit_count );
+    //! Submit a single byte for input processing
     void  process_byte( unsigned char byte );
+    //! Submit a memory block for input processing, iterator-pair style
     void  process_block( void const *bytes_begin, void const *bytes_end );
+    //! Submit a memory block for input processing, pointer-and-size style
     void  process_bytes( void const *buffer, std::size_t byte_count );
 
+    //! Return the checksum of the already-processed bits
     value_type  checksum() const;
 
 private:
@@ -164,6 +229,35 @@
 
 //  Optimized cyclic redundancy code (CRC) class declaration  ----------------//
 
+/** Objects of this type compute the CRC checksum of submitted data, where said
+    data can be entered piecemeal through several different kinds of groupings.
+    Modulo-2 polynomial division steps are performed byte-wise, aided by the use
+    of pre-computation tables.  Said division uses the altered algorithm, so any
+    data has to be unaugmented.
+
+    \pre  0 \< \a Bits \<= \c std::numeric_limits&lt;uintmax_t&gt;::digits
+
+    \tparam Bits  The order of the modulo-2 polynomial divisor.  (\e Width from
+      the RMCA)
+    \tparam TruncPoly  The lowest coefficients of the divisor polynomial.  The
+      highest-order coefficient is omitted and always assumed to be 1.  Defaults
+      to \c 0, i.e. the only non-zero term is the implicit one for
+      x<sup><var>Bits</var></sup>.  (\e Poly from the RMCA)
+    \tparam InitRem  The (unaugmented) initial state of the polynomial
+      remainder.  Defaults to \c 0 if omitted.  (\e Init from the RMCA)
+    \tparam FinalXor  The (XOR) bit-mask to be applied to the output remainder,
+      after possible reflection but before returning.  Defaults to \c 0 (i.e. no
+      bit changes) if omitted.  (\e XorOut from the RMCA)
+    \tparam ReflectIn  If \c true, input bytes are read lowest-order bit first,
+      otherwise highest-order bit first.  Defaults to \c false if omitted.
+      (\e RefIn from the RMCA)
+    \tparam ReflectRem  If \c true, the output remainder is reflected before the
+      XOR-mask.  Defaults to \c false if omitted.  (\e RefOut from the RMCA)
+
+    \todo  Get rid of the default value for \a TruncPoly.  Choosing a divisor is
+      an important decision with many factors, so a default is never useful,
+      especially a bad one.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -171,38 +265,59 @@
 {
 public:
     // Type
+    //! \copydoc  boost::crc_basic::value_type
     typedef typename boost::uint_t<Bits>::fast  value_type;
 
     // Constants for the template parameters
+    //! \copydoc  boost::crc_basic::bit_count
     BOOST_STATIC_CONSTANT( std::size_t, bit_count = Bits );
+    //! A copy of \a TruncPoly provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( value_type, truncated_polynominal = TruncPoly );
+    //! A copy of \a InitRem provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( value_type, initial_remainder = InitRem );
+    //! A copy of \a FinalXor provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( value_type, final_xor_value = FinalXor );
+    //! A copy of \a ReflectIn provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( bool, reflect_input = ReflectIn );
+    //! A copy of \a ReflectRem provided for meta-programming purposes
     BOOST_STATIC_CONSTANT( bool, reflect_remainder = ReflectRem );
 
-    // Constructor
+    // Constructor (use the automatic copy-ctr, move-ctr, and dtr)
+    //! Create a computer, giving an initial remainder if desired
     explicit  crc_optimal( value_type init_rem = InitRem );
 
     // Internal Operations
+    //! \copybrief  boost::crc_basic::get_truncated_polynominal
     value_type  get_truncated_polynominal() const;
+    //! \copybrief  boost::crc_basic::get_initial_remainder
     value_type  get_initial_remainder() const;
+    //! \copybrief  boost::crc_basic::get_final_xor_value
     value_type  get_final_xor_value() const;
+    //! \copybrief  boost::crc_basic::get_reflect_input
     bool        get_reflect_input() const;
+    //! \copybrief  boost::crc_basic::get_reflect_remainder
     bool        get_reflect_remainder() const;
 
+    //! \copybrief  boost::crc_basic::get_interim_remainder
     value_type  get_interim_remainder() const;
+    //! Change the interim remainder to either a given value or the initial one
     void        reset( value_type new_rem = InitRem );
 
     // External Operations
+    //! \copybrief  boost::crc_basic::process_byte
     void  process_byte( unsigned char byte );
+    //! \copybrief  boost::crc_basic::process_block
     void  process_block( void const *bytes_begin, void const *bytes_end );
+    //! \copybrief  boost::crc_basic::process_bytes
     void  process_bytes( void const *buffer, std::size_t byte_count );
 
+    //! \copybrief  boost::crc_basic::checksum
     value_type  checksum() const;
 
     // Operators
+    //! Submit a single byte for input processing, suitable for the STL
     void        operator ()( unsigned char byte );
+    //! Return the checksum of the already-processed bits, suitable for the STL
     value_type  operator ()() const;
 
 private:
@@ -231,6 +346,7 @@
 
 //  Implementation detail stuff  ---------------------------------------------//
 
+//! \cond
 namespace detail
 {
     // Single-bit mask constant, MPL-style
@@ -482,10 +598,46 @@
 
 
 }  // namespace detail
+//! \endcond
 
 
 //  Simple CRC class function definitions  -----------------------------------//
 
+/** Constructs a \c crc_basic object with at least the required parameters to a
+    particular CRC formula to be processed upon receiving input.
+
+    \param[in] truncated_polynominal  The lowest coefficients of the divisor
+      polynomial.  The highest-order coefficient is omitted and always assumed
+      to be 1.  (\e Poly from the RMCA)
+    \param[in] initial_remainder  The (unaugmented) initial state of the
+      polynomial remainder.  Defaults to \c 0 if omitted.  (\e Init from the
+      RMCA)
+    \param[in] final_xor_value  The (XOR) bit-mask to be applied to the output
+      remainder, after possible reflection but before returning.  Defaults to
+      \c 0 (i.e. no bit changes) if omitted.  (\e XorOut from the RMCA)
+    \param[in] reflect_input  If \c true, input bytes are read lowest-order bit
+      first, otherwise highest-order bit first.  Defaults to \c false if
+      omitted.  (\e RefIn from the RMCA)
+    \param[in] reflect_remainder  If \c true, the output remainder is reflected
+      before the XOR-mask.  Defaults to \c false if omitted.  (\e RefOut from
+      the RMCA)
+
+    \post  <code><var>truncated_polynominal</var> ==
+      this-&gt;get_truncated_polynominal()</code>
+    \post  <code><var>initial_remainder</var> ==
+      this-&gt;get_initial_remainder()</code>
+    \post  <code><var>final_xor_value</var> ==
+      this-&gt;get_final_xor_value()</code>
+    \post  <code><var>reflect_input</var> ==
+      this-&gt;get_reflect_input()</code>
+    \post  <code><var>reflect_remainder</var> ==
+      this-&gt;get_reflect_remainder()</code>
+    \post  <code><var>initial_remainder</var> ==
+      this-&gt;get_interim_remainder()</code>
+    \post  <code>(<var>reflect_remainder</var> ?
+      REFLECT(<var>initial_remainder</var>) : <var>initial_remainder</var>) ^
+      <var>final_xor_value</var> == this-&gt;checksum()</code>
+ */
 template < std::size_t Bits >
 inline
 crc_basic<Bits>::crc_basic
@@ -502,6 +654,14 @@
 {
 }
 
+/** Returns a representation of the polynomial divisor.  The value of the
+    2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+    x<sup>i</sup> term.  The omitted bit for x<sup>#bit_count</sup> is always 1.
+
+    \return  The bit-packed list of coefficients.  If the bit-length of
+      #value_type exceeds #bit_count, the values of higher-placed bits should be
+      ignored (even any for x<sup>#bit_count</sup>) since they're unregulated.
+ */
 template < std::size_t Bits >
 inline
 typename crc_basic<Bits>::value_type
@@ -512,6 +672,14 @@
     return poly_;
 }
 
+/** Returns a representation of the polynomial remainder before any input has
+    been submitted.  The value of the 2<sup>i</sup> bit is the value of the
+    coefficient of the polynomial's x<sup>i</sup> term.
+
+    \return  The bit-packed list of coefficients.  If the bit-length of
+      #value_type exceeds #bit_count, the values of higher-placed bits should be
+      ignored since they're unregulated.
+ */
 template < std::size_t Bits >
 inline
 typename crc_basic<Bits>::value_type
@@ -522,6 +690,15 @@
     return init_;
 }
 
+/** Returns the mask to be used during creation of a checksum.  The mask is used
+    for an exclusive-or (XOR) operation applied bit-wise to the interim
+    remainder representation (after any reflection, if #get_reflect_remainder()
+    returns \c true).
+
+    \return  The bit-mask.  If the bit-length of #value_type exceeds #bit_count,
+      the values of higher-placed bits should be ignored since they're
+      unregulated.
+ */
 template < std::size_t Bits >
 inline
 typename crc_basic<Bits>::value_type
@@ -532,6 +709,13 @@
     return final_;
 }
 
+/** Returns a whether or not a submitted byte will be \"reflected\" before it is
+    used to update the interim remainder.  Only the byte-wise operations
+    #process_byte, #process_block, and #process_bytes are affected.
+
+    \retval true  Input bytes will be read starting from the lowest-order bit.
+    \retval false  Input bytes will be read starting from the highest-order bit.
+ */
 template < std::size_t Bits >
 inline
 bool
@@ -542,6 +726,12 @@
     return rft_in_;
 }
 
+/** Indicates if the interim remainder will be \"reflected\" before it is passed
+    to the XOR-mask stage when returning a checksum.
+
+    \retval true  The interim remainder is reflected before further work.
+    \retval false  The interim remainder is applied to the XOR-mask as-is.
+ */
 template < std::size_t Bits >
 inline
 bool
@@ -552,6 +742,19 @@
     return rft_out_;
 }
 
+/** Returns a representation of the polynomial remainder after all the input
+    submissions since construction or the last #reset call.  The value of the
+    2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+    x<sup>i</sup> term.  If CRC processing gets interrupted here, retain the
+    value returned, and use it to start up the next CRC computer where you left
+    off (with #reset(value_type) or construction).  The next computer has to
+    have its other parameters compatible with this computer.
+
+    \return  The bit-packed list of coefficients.  If the bit-length of
+      #value_type exceeds #bit_count, the values of higher-placed bits should be
+      ignored since they're unregulated.  No output processing (reflection or
+      XOR mask) has been applied to the value.
+ */
 template < std::size_t Bits >
 inline
 typename crc_basic<Bits>::value_type
@@ -562,6 +765,19 @@
     return rem_ & detail::low_bits_mask_c<Bits>::value;
 }
 
+/** Changes the interim polynomial remainder to \a new_rem, purging any
+    influence previously submitted input has had.  The value of the
+    2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+    x<sup>i</sup> term.
+
+    \param[in] new_rem  The (unaugmented) state of the polynomial remainder
+      starting from this point, with no output processing applied.
+
+    \post  <code><var>new_rem</var> == this-&gt;get_interim_remainder()</code>
+    \post  <code>((this-&gt;get_reflect_remainder() ?
+      REFLECT(<var>new_rem</var>) : <var>new_rem</var>) ^
+      this-&gt;get_final_xor_value()) == this-&gt;checksum()</code>
+ */
 template < std::size_t Bits >
 inline
 void
@@ -573,6 +789,18 @@
     rem_ = new_rem;
 }
 
+/** Changes the interim polynomial remainder to the initial remainder given
+    during construction, purging any influence previously submitted input has
+    had.  The value of the 2<sup>i</sup> bit is the value of the coefficient of
+    the polynomial's x<sup>i</sup> term.
+
+    \post  <code>this-&gt;get_initial_remainder() ==
+      this-&gt;get_interim_remainder()</code>
+    \post  <code>((this-&gt;get_reflect_remainder() ?
+      REFLECT(this-&gt;get_initial_remainder()) :
+      this-&gt;get_initial_remainder()) ^ this-&gt;get_final_xor_value())
+      == this-&gt;checksum()</code>
+ */
 template < std::size_t Bits >
 inline
 void
@@ -583,6 +811,13 @@
     this->reset( this->get_initial_remainder() );
 }
 
+/** Updates the interim remainder with a single altered-CRC-division step.
+
+    \param[in] bit  The new input bit.
+
+    \post  The interim remainder is updated though a modulo-2 polynomial
+      division, where the division steps are altered for unaugmented CRCs.
+ */
 template < std::size_t Bits >
 inline
 void
@@ -594,6 +829,21 @@
     detail::crc_modulo_update<Bits>( rem_, bit, poly_ );
 }
 
+/** Updates the interim remainder with several altered-CRC-division steps.  Each
+    bit is processed separately, starting from the one at the
+    2<sup><var>bit_count</var> - 1</sup> place, then proceeding down to the
+    lowest-placed bit.  Any order imposed by
+    <code>this-&gt;get_reflect_input()</code> is ignored.
+
+    \pre  0 \< \a bit_count \<= \c CHAR_BIT
+
+    \param[in] bits  The byte containing the new input bits.
+    \param[in] bit_count  The number of bits in the byte to be read.
+
+    \post  The interim remainder is updated though \a bit_count modulo-2
+      polynomial divisions, where the division steps are altered for unaugmented
+      CRCs.
+ */
 template < std::size_t Bits >
 void
 crc_basic<Bits>::process_bits
@@ -613,6 +863,17 @@
     }
 }
 
+/** Updates the interim remainder with a byte's worth of altered-CRC-division
+    steps.  The bits within the byte are processed from the highest place down
+    if <code>this-&gt;get_reflect_input()</code> is \c false, and lowest place
+    up otherwise.
+
+    \param[in] byte  The new input byte.
+
+    \post  The interim remainder is updated though \c CHAR_BIT modulo-2
+      polynomial divisions, where the division steps are altered for unaugmented
+      CRCs.
+ */
 template < std::size_t Bits >
 inline
 void
@@ -624,6 +885,30 @@
     process_bits( (rft_in_ ? detail::reflect_byte( byte ) : byte), CHAR_BIT );
 }
 
+/** Updates the interim remainder with several bytes' worth of
+    altered-CRC-division steps.  The bits within each byte are processed from
+    the highest place down if <code>this-&gt;get_reflect_input()</code> is
+    \c false, and lowest place up otherwise.  The bytes themselves are processed
+    starting from the one pointed by \a bytes_begin until \a bytes_end is
+    reached through forward iteration, treating the two pointers as if they
+    point to <code>unsigned char</code> objects.
+
+    \pre  \a bytes_end has to equal \a bytes_begin if the latter is \c NULL or
+      otherwise doesn't point to a valid buffer.
+    \pre  \a bytes_end, if not equal to \a bytes_begin, has to point within or
+      one-byte-past the same buffer \a bytes_begin points into.
+    \pre  \a bytes_end has to be reachable from \a bytes_begin through a finite
+      number of forward byte-pointer increments.
+
+    \param[in] bytes_begin  The address where the memory block begins.
+    \param[in] bytes_end  Points to one-byte past the address of the memory
+      block's last byte, or \a bytes_begin if no bytes are to be read.
+
+    \post  The interim remainder is updated though <code>CHAR_BIT * (((unsigned
+      char const *) bytes_end) - ((unsigned char const *) bytes_begin))</code>
+      modulo-2 polynomial divisions, where the division steps are altered for
+      unaugmented CRCs.
+ */
 template < std::size_t Bits >
 void
 crc_basic<Bits>::process_block
@@ -639,6 +924,26 @@
     }
 }
 
+/** Updates the interim remainder with several bytes' worth of
+    altered-CRC-division steps.  The bits within each byte are processed from
+    the highest place down if <code>this-&gt;get_reflect_input()</code> is
+    \c false, and lowest place up otherwise.  The bytes themselves are processed
+    starting from the one pointed by \a buffer, forward-iterated (as if the
+    pointed-to objects were of <code>unsigned char<code>) until \a byte_count
+    bytes are read.
+
+    \pre  \a byte_count has to equal 0 if \a buffer is \c NULL or otherwise
+      doesn't point to valid memory.
+    \pre  If \a buffer points within valid memory, then that block has to have
+      at least \a byte_count more valid bytes allocated from that point.
+
+    \param[in] buffer  The address where the memory block begins.
+    \param[in] byte_count  The number of bytes in the memory block.
+
+    \post  The interim remainder is updated though <code>CHAR_BIT *
+      <var>byte_count</var></code> modulo-2 polynomial divisions, where the
+      division steps are altered for unaugmented CRCs.
+ */
 template < std::size_t Bits >
 inline
 void
@@ -654,6 +959,18 @@
     process_block( b, b + byte_count );
 }
 
+/** Computes the checksum of all the submitted bits since construction or the
+    last call to #reset.  The checksum will be the raw checksum, i.e. the
+    (interim) remainder after all the modulo-2 polynomial division, plus any
+    output processing.
+
+    \return  <code>(this-&gt;get_reflect_remainder() ?
+      REFLECT(this-&gt;get_interim_remainder()) :
+      this-&gt;get_interim_remainder()) ^ this-&gt;get_final_xor_value()</code>
+
+    \note  Since checksums are meant to be compared, any higher-placed bits
+      (when the bit-length of #value_type exceeds #bit_count) will be set to 0.
+ */
 template < std::size_t Bits >
 inline
 typename crc_basic<Bits>::value_type
@@ -672,6 +989,22 @@
 #define BOOST_CRC_OPTIMAL_NAME  crc_optimal<Bits, TruncPoly, InitRem, \
  FinalXor, ReflectIn, ReflectRem>
 
+/** Constructs a \c crc_optimal object with a particular CRC formula to be
+    processed upon receiving input.  The initial remainder may be overridden.
+
+    \param[in] init_rem  The (unaugmented) initial state of the polynomial
+      remainder.  Defaults to #initial_remainder if omitted.
+
+    \post  <code>#truncated_polynominal ==
+      this-&gt;get_truncated_polynominal()</code>
+    \post  <code>#initial_remainder == this-&gt;get_initial_remainder()</code>
+    \post  <code>#final_xor_value == this-&gt;get_final_xor_value()</code>
+    \post  <code>#reflect_input == this-&gt;get_reflect_input()</code>
+    \post  <code>#reflect_remainder == this-&gt;get_reflect_remainder()</code>
+    \post  <code><var>init_rem</var> == this-&gt;get_interim_remainder()</code>
+    \post  <code>(#reflect_remainder ? REFLECT(<var>init_rem</var>) :
+      <var>init_rem</var>) ^ #final_xor_value == this-&gt;checksum()</code>
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -685,6 +1018,7 @@
     crc_table_type::init_table();
 }
 
+//! \copydetails  boost::crc_basic::get_truncated_polynominal
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -697,6 +1031,7 @@
     return TruncPoly;
 }
 
+//! \copydetails  boost::crc_basic::get_initial_remainder
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -709,6 +1044,7 @@
     return InitRem;
 }
 
+//! \copydetails  boost::crc_basic::get_final_xor_value
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -721,6 +1057,7 @@
     return FinalXor;
 }
 
+//! \copydetails  boost::crc_basic::get_reflect_input
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -733,6 +1070,7 @@
     return ReflectIn;
 }
 
+//! \copydetails  boost::crc_basic::get_reflect_remainder
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -745,6 +1083,7 @@
     return ReflectRem;
 }
 
+//! \copydetails  boost::crc_basic::get_interim_remainder
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -758,6 +1097,20 @@
     return helper_type::reflect( rem_ ) & detail::low_bits_mask_c<Bits>::value;
 }
 
+/** Changes the interim polynomial remainder to \a new_rem, purging any
+    influence previously submitted input has had.  The value of the
+    2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+    x<sup>i</sup> term.
+
+    \param[in] new_rem  The (unaugmented) state of the polynomial remainder
+      starting from this point, with no output processing applied.  Defaults to
+      <code>this-&gt;get_initial_remainder()</code> if omitted.
+
+    \post  <code><var>new_rem</var> == this-&gt;get_interim_remainder()</code>
+    \post  <code>((this-&gt;get_reflect_remainder() ?
+      REFLECT(<var>new_rem</var>) : <var>new_rem</var>) ^
+      this-&gt;get_final_xor_value()) == this-&gt;checksum()</code>
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -771,6 +1124,12 @@
     rem_ = helper_type::reflect( new_rem );
 }
 
+/** \copydetails  boost::crc_basic::process_byte
+
+    \note  Any modulo-2 polynomial divisions may use a table of pre-computed
+      remainder changes (as XOR masks) to speed computation when reading data
+      byte-wise.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -784,6 +1143,12 @@
     process_bytes( &byte, sizeof(byte) );
 }
 
+/** \copydetails  boost::crc_basic::process_block
+
+    \note  Any modulo-2 polynomial divisions may use a table of pre-computed
+      remainder changes (as XOR masks) to speed computation when reading data
+      byte-wise.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -808,6 +1173,12 @@
     }
 }
 
+/** \copydetails  boost::crc_basic::process_bytes
+
+    \note  Any modulo-2 polynomial divisions may use a table of pre-computed
+      remainder changes (as XOR masks) to speed computation when reading data
+      byte-wise.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -824,6 +1195,7 @@
     process_block( b, b + byte_count );
 }
 
+//! \copydetails  boost::crc_basic::checksum
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -837,6 +1209,25 @@
      & detail::low_bits_mask_c<Bits>::value;
 }
 
+/** Updates the interim remainder with a byte's worth of altered-CRC-division
+    steps.  The bits within the byte are processed from the highest place down
+    if <code>this-&gt;get_reflect_input()</code> is \c false, and lowest place
+    up otherwise.  This function is meant to present a function-object interface
+    to code that wants to process a stream of bytes with
+    <code>std::for_each</code> or similar range-processing algorithms.  Since
+    some of these algorithms takes their function object by value, make sure to
+    copy back the result to this object so the updates can be remembered.
+
+    \param[in] byte  The new input byte.
+
+    \post  The interim remainder is updated though \c CHAR_BIT modulo-2
+      polynomial divisions, where the division steps are altered for unaugmented
+      CRCs.
+
+    \note  Any modulo-2 polynomial divisions may use a table of pre-computed
+      remainder changes (as XOR masks) to speed computation when reading data
+      byte-wise.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -850,6 +1241,22 @@
     process_byte( byte );
 }
 
+/** Computes the checksum of all the submitted bits since construction or the
+    last call to #reset.  The checksum will be the raw checksum, i.e. the
+    (interim) remainder after all the modulo-2 polynomial division, plus any
+    output processing.  This function is meant to present a function-object
+    interface to code that wants to receive data like
+    <code>std::generate_n</code> or similar data-processing algorithms.  Note
+    that if this object is used as a generator multiple times without an
+    intervening mutating operation, the same value will always be returned.
+
+    \return  <code>(this-&gt;get_reflect_remainder() ?
+      REFLECT(this-&gt;get_interim_remainder()) :
+      this-&gt;get_interim_remainder()) ^ this-&gt;get_final_xor_value()</code>
+
+    \note  Since checksums are meant to be compared, any higher-placed bits
+      (when the bit-length of #value_type exceeds #bit_count) will be set to 0.
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -865,6 +1272,43 @@
 
 //  CRC computation function definition  -------------------------------------//
 
+/** Computes the polynomial remainder of a CRC run, assuming that \a buffer and
+    \a byte_count describe a memory block representing the polynomial dividend.
+    The division steps are altered so the result directly gives a checksum,
+    without need to augment the memory block with scratch-space bytes.  The
+    first byte is considered the highest order, going down for subsequent bytes.
+
+    \pre  0 \< \a Bits \<= \c std::numeric_limits&lt;uintmax_t&gt;::digits
+
+    \tparam Bits  The order of the modulo-2 polynomial divisor.  (\e Width from
+      the RMCA)
+    \tparam TruncPoly  The lowest coefficients of the divisor polynomial.  The
+      highest-order coefficient is omitted and always assumed to be 1.
+      (\e Poly from the RMCA)
+    \tparam InitRem  The (unaugmented) initial state of the polynomial
+      remainder.  (\e Init from the RMCA)
+    \tparam FinalXor  The (XOR) bit-mask to be applied to the output remainder,
+      after possible reflection but before returning.  (\e XorOut from the RMCA)
+    \tparam ReflectIn  If \c True, input bytes are read lowest-order bit first,
+      otherwise highest-order bit first.  (\e RefIn from the RMCA)
+    \tparam ReflectRem  If \c True, the output remainder is reflected before the
+      XOR-mask.  (\e RefOut from the RMCA)
+
+    \param[in] buffer  The address where the memory block begins.
+    \param[in] byte_count  The number of bytes in the memory block.
+
+    \return  The checksum, which is the last (interim) remainder plus any output
+      processing.
+
+    \note  Unaugmented-style CRC runs perform modulo-2 polynomial division in
+      an altered order.  The trailing \a Bits number of zero-valued bits needed
+      to extracted an (unprocessed) checksum is virtually moved to near the
+      beginning of the message.  This is OK since the XOR operation is
+      commutative and associative.  It also means that you can get a checksum
+      anytime.  Since data is being read byte-wise, a table of pre-computed
+      remainder changes (as XOR masks) can be used to speed computation.
+
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
            BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
            bool ReflectIn, bool ReflectRem >
@@ -885,6 +1329,52 @@
 
 //  Augmented-message CRC computation function definition  -------------------//
 
+/** Computes the polynomial remainder of a CRC run, assuming that \a buffer and
+    \a byte_count describe a memory block representing the polynomial dividend.
+    The first byte is considered the highest order, going down for subsequent
+    bytes.  Within a byte, the highest-order bit is read first (corresponding to
+    \e RefIn = \c False in the RMCA).  Check the other parts of this function's
+    documentation to see how a checksum can be gained and/or used.
+
+    \pre  0 \< \a Bits \<= \c std::numeric_limits&lt;uintmax_t&gt;::digits
+
+    \tparam Bits  The order of the modulo-2 polynomial divisor.  (\e Width from
+      the RMCA)
+    \tparam TruncPoly  The lowest coefficients of the divisor polynomial.  The
+      highest-order coefficient is omitted and always assumed to be 1.
+      (\e Poly from the RMCA)
+
+    \param[in] buffer  The address where the memory block begins.
+    \param[in] byte_count  The number of bytes in the memory block.
+    \param[in] initial_remainder  The initial state of the polynomial
+      remainder, defaulting to zero if omitted.  If you are reading a memory
+      block in multiple runs, put the return value of the previous run here.
+      (Note that initial-remainders given by RMCA parameter lists, as
+      \e Init, assume that the initial remainder is in its \b unaugmented state,
+      so you would need to convert the value to make it suitable for this
+      function.  I currently don't provide a conversion routine.)
+
+    \return  The interim remainder, if no augmentation is used.  A special value
+      if augmentation is used (see the notes).  No output processing is done on
+      the value.  (In RMCA terms, \e RefOut is \c False and \e XorOut is \c 0.)
+
+    \note  Augmented-style CRC runs use straight-up modulo-2 polynomial
+      division.  Since data is being read byte-wise, a table of pre-computed
+      remainder changes (as XOR masks) can be used to speed computation.
+    \note  Reading just a memory block will yield an interim remainder, and not
+      the final checksum.  To get that checksum, allocate \a Bits / \c CHAR_BIT
+      bytes directly after the block and fill them with zero values, then extend
+      \a byte_count to include those extra bytes.  A data block is corrupt if
+      the return value doesn't equal your separately given checksum.
+    \note  Another way to perform a check is use the zero-byte extension method,
+      but replace the zero values with your separately-given checksum.  The
+      checksum must be loaded in big-endian order.  Here corruption, in either
+      the data block or the given checksum, is confirmed if the return value is
+      not zero.
+    \note  The two checksum techniques assume the CRC-run is performed bit-wise,
+      while this function works byte-wise.  That means that the techniques can
+      be used only if \c CHAR_BIT divides \a Bits evenly!
+ */
 template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly >
 typename uint_t<Bits>::fast
 augmented_crc