First commit of extensively revised documentation including examples for all items and using Quickbook code snippets in the text. TODO Compile failure in common_factor_ct example. Derived html files NOT saved.

doc/Jamfile.v2

@@ -1,12 +1,88 @@
-
+# jamfile to build Boost.Integer Documentation.
 
 # Copyright John Maddock 2005. Use, modification, and distribution are
 # subject to the Boost Software License, Version 1.0. (See accompanying
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-using quickbook ;
+# revised to include Doxygen and Autoindex
+# Copyright Paul A. Bristow 2015
+
+using boostbook ;
+using doxygen ;  # Required if you want to use Doxygen.
+using quickbook ;
+using auto-index ;
+
+path-constant here : . ; # convenient to refer to files in the same directory as this jamfile.v2
+path-constant parent : .. ;  # Parent directory, /libs/integer/
+
+if --enable-index in  [ modules.peek : ARGV ]
+{
+   ECHO "Building the Integer docs with automatic index generation enabled." ;
+   using auto-index ;
+   project integer_doc : requirements
+             <auto-index>on
+             <auto-index-script>integer.idx
+             <auto-index-prefix>.
+             <auto-index-verbose>on
+             <format>html:<auto-index-internal>on
+             <format>html:<xsl:param>generate.index=0
+             <format>pdf:<auto-index-internal>on
+             <format>pdf:<xsl:param>index.on.type=1
+             <quickbook-define>enable_index ;
+}
+else
+{
+   project integer_doc ;
+   ECHO "Building the Integer docs with automatic index generation disabled. Try building with --enable-index." ;
+}
+
+
+xml integer
+   :
+    integer.qbk # This is 'root' Quickbook file (that may include other .qbk files).
+   ;
+
+doxygen autodoc
+  :
+    [ glob $(here)/../include/boost/*.hpp ]
+    [ glob $(here)/../include/boost/integer/integer/*.hpp ]
+    # but could also include this and switch Boost.Integer C++ reference info to include implementation details (or not) using Doxygen macro DETAIL.
+    # See http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcond
+    # and http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_enabled_sections
+    # by adding this line below with other Doxygen parameters
+    #     <doxygen:param>ENABLED_SECTIONS="DETAIL"
+    #  Or setting this macro value ENABLED_SECTIONS="DETAIL" in /doxygen/integer_doxyfile.txt for Standalone Doxygen documentaation.
+    # This might be useful for maintainers.
+
+  :
+    <doxygen:param>PROJECT_NAME="Integer"
+    <doxygen:param>RECURSIVE=NO # Specify all folders and files above explicitly.
+    <doxygen:param>ENABLE_PREPROCESSING=YES
+    <doxygen:param>EXPAND_ONLY_PREDEF=YES
+    <doxygen:param>EXTRACT_ALL=NO
+    <doxygen:param>EXTRACT_PRIVATE=NO
+    <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+    <doxygen:param>MACRO_EXPANSION=YES
+    <doxygen:param>SORT_MEMBER_DOCS=NO
+    <doxygen:param>SHOW_INCLUDE_FILES=NO
+    <doxygen:param>MAX_INITIALIZER_LINES=0
+    <doxygen:param>VERBATIM_HEADERS=NO
+    <doxygen:param>WARNINGS=NO # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings for undocumented members.
+    # If EXTRACT_ALL is set to YES then this flag will automatically be disabled.
+    <doxygen:param>WARN_IF_UNDOCUMENTED=YES # If WARN_IF_UNDOCUMENTED is set to YES,
+    # then doxygen will generate warnings for all undocumented members.
+    <doxygen:param>WARN_IF_DOC_ERROR=YES # If WARN_IF_DOC_ERROR is set to YES, Doxygen will generate warnings for
+    # potential errors in the documentation.
+    <doxygen:param>WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen.
+    # Much better to send message to a logfile than the default stderr.
+    # and make sure that there are no Doxygen errors or significant warnings in the log file.
+
+    #<reftitle>"Reference" # Default is "Reference" but helpful to specify library.
+    <xsl:param>"boost.doxygen.reftitle=Boost.Integer C++ Reference"
+    # See Doxygen configuration for detailed explanation of these options.
+    # Usually these match those in /doc/doxygen/integer_doxyfile.txt.
+  ;
 
-xml integer : integer.qbk ;
 boostbook standalone
     :
         integer
@@ -14,6 +90,7 @@ boostbook standalone
         # HTML options first:
         # Use graphics not text for navigation:
         <xsl:param>navig.graphics=1
+        <xsl:param>chapter.autolabel=0 # No Chapter numbering.
         # How far down we chunk nested sections, basically all of them:
         <xsl:param>chunk.section.depth=1
         # Don't put the first section on the same page as the TOC:
@@ -26,7 +103,7 @@ boostbook standalone
         <xsl:param>generate.section.toc.level=4
         # Path for links to Boost:
         <xsl:param>boost.root=../../../..
-        
+
         # PDF Options:
         # TOC Generation: this is needed for FOP-0.9 and later:
         <xsl:param>fop1.extensions=0
@@ -47,7 +124,11 @@ boostbook standalone
         # better use SVG's instead:
         <format>pdf:<xsl:param>admon.graphics.extension=".svg"
         <format>pdf:<xsl:param>admon.graphics.path=$(boost-images)/
-        <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/regex/doc/html
+        #<format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/regex/doc/html
+        # Not sure if this line is correct?
+
+       <dependency>autodoc # Add Doxygen info.
+
     ;
 
 install pdfinstall : standalone/<format>pdf : <location>. <install-type>PDF ;

include/boost/integer.hpp

@@ -6,6 +6,9 @@
 
 //  See http://www.boost.org/libs/integer for documentation.
 
+//! \file
+//! \brief Compile-time evaluation of specified (least and fast) integer types.
+
 //  Revision History
 //   22 Sep 01  Added value-based integer templates. (Daryle Walker)
 //   01 Apr 01  Modified to use new <boost/limits.hpp> header. (John Maddock)
@@ -42,15 +45,16 @@ namespace boost
   //  fast integers from least integers
   //  int_fast_t<> works correctly for unsigned too, in spite of the name.
   template< typename LeastInt >
-  struct int_fast_t 
+  struct int_fast_t
-  { 
+  {
-     typedef LeastInt fast; 
+     typedef LeastInt fast;
      typedef fast     type;
   }; // imps may specialize
 
+//! \cond DETAIL
   namespace detail{
 
-  //  convert category to type 
+  //  convert category to type
   template< int Category > struct int_least_helper {}; // default is empty
   template< int Category > struct uint_least_helper {}; // default is empty
 
@@ -104,8 +108,8 @@ namespace boost
   template <> struct exact_unsigned_base_helper<sizeof(boost::ulong_long_type)* CHAR_BIT> { typedef boost::ulong_long_type exact; };
 #endif
 
-
   } // namespace detail
+  //! \endcond // DETAIL
 
   //  integer templates specifying number of bits  ---------------------------//
 
@@ -138,7 +142,7 @@ namespace boost
          "No suitable unsigned integer type with the requested number of bits is available.");
 #if (defined(__BORLANDC__) || defined(__CODEGEAR__)) && defined(BOOST_NO_INTEGRAL_INT64_T)
      // It's really not clear why this workaround should be needed... shrug I guess!  JM
-     BOOST_STATIC_CONSTANT(int, s = 
+     BOOST_STATIC_CONSTANT(int, s =
            6 +
           (Bits <= ::std::numeric_limits<unsigned long>::digits) +
           (Bits <= ::std::numeric_limits<unsigned int>::digits) +
@@ -147,7 +151,7 @@ namespace boost
      typedef typename detail::int_least_helper< ::boost::uint_t<Bits>::s>::least least;
 #else
       typedef typename boost::detail::uint_least_helper
-        < 
+        <
 #ifdef BOOST_HAS_LONG_LONG
           (Bits <= (int)(sizeof(boost::long_long_type) * CHAR_BIT)) +
 #else
@@ -171,7 +175,7 @@ namespace boost
 #else
   template< long MaxValue >   // maximum value to require support
 #endif
-  struct int_max_value_t 
+  struct int_max_value_t
   {
       typedef typename boost::detail::int_least_helper
         <
@@ -193,7 +197,7 @@ namespace boost
 #else
   template< long MinValue >   // minimum value to require support
 #endif
-  struct int_min_value_t 
+  struct int_min_value_t
   {
       typedef typename boost::detail::int_least_helper
         <
@@ -216,12 +220,12 @@ namespace boost
 #else
   template< unsigned long MaxValue >   // minimum value to require support
 #endif
-  struct uint_value_t 
+  struct uint_value_t
   {
 #if (defined(__BORLANDC__) || defined(__CODEGEAR__))
      // It's really not clear why this workaround should be needed... shrug I guess!  JM
 #if defined(BOOST_NO_INTEGRAL_INT64_T)
-      BOOST_STATIC_CONSTANT(unsigned, which = 
+      BOOST_STATIC_CONSTANT(unsigned, which =
            1 +
           (MaxValue <= ::boost::integer_traits<unsigned long>::const_max) +
           (MaxValue <= ::boost::integer_traits<unsigned int>::const_max) +
@@ -229,7 +233,7 @@ namespace boost
           (MaxValue <= ::boost::integer_traits<unsigned char>::const_max));
       typedef typename detail::int_least_helper< ::boost::uint_value_t<MaxValue>::which>::least least;
 #else // BOOST_NO_INTEGRAL_INT64_T
-      BOOST_STATIC_CONSTANT(unsigned, which = 
+      BOOST_STATIC_CONSTANT(unsigned, which =
            1 +
           (MaxValue <= ::boost::integer_traits<boost::ulong_long_type>::const_max) +
           (MaxValue <= ::boost::integer_traits<unsigned long>::const_max) +
@@ -240,7 +244,7 @@ namespace boost
 #endif // BOOST_NO_INTEGRAL_INT64_T
 #else
       typedef typename boost::detail::uint_least_helper
-        < 
+        <
 #if !defined(BOOST_NO_INTEGRAL_INT64_T) && defined(BOOST_HAS_LONG_LONG)
           (MaxValue <= ::boost::integer_traits<boost::ulong_long_type>::const_max) +
 #else
@@ -255,7 +259,6 @@ namespace boost
       typedef typename int_fast_t<least>::type  fast;
   };
 
-
 } // namespace boost
 
 #endif  // BOOST_INTEGER_HPP

include/boost/integer/common_factor.hpp

@@ -5,7 +5,9 @@
 //  accompanying file LICENSE_1_0.txt or copy at
 //  http://www.boost.org/LICENSE_1_0.txt)
 
-//  See http://www.boost.org for updates, documentation, and revision history. 
+//  See http://www.boost.org for updates, documentation, and revision history.
+//! \file
+//! \brief Include both GCD and LCM.
 
 #ifndef BOOST_INTEGER_COMMON_FACTOR_HPP
 #define BOOST_INTEGER_COMMON_FACTOR_HPP

include/boost/integer/common_factor_ct.hpp

@@ -5,7 +5,9 @@
 //  accompanying file LICENSE_1_0.txt or copy at
 //  http://www.boost.org/LICENSE_1_0.txt)
 
-//  See http://www.boost.org for updates, documentation, and revision history. 
+//  See http://www.boost.org for updates, documentation, and revision history.
+//! \file
+//! \brief Evaluate Greatest Common Divisor at compile-time.
 
 #ifndef BOOST_INTEGER_COMMON_FACTOR_CT_HPP
 #define BOOST_INTEGER_COMMON_FACTOR_CT_HPP
@@ -17,9 +19,10 @@ namespace boost
 {
 namespace integer
 {
+  // Warning:  this is from 1.58 in namespace boost::integer and no longer in namespace boost::math.
 
 //  Implementation details  --------------------------------------------------//
-
+//! \cond DETAIL
 namespace detail
 {
     // Build GCD with Euclid's recursive algorithm
@@ -71,7 +74,7 @@ namespace detail
     };
 
 }  // namespace detail
-
+//! \endcond // DETAIL
 
 //  Compile-time greatest common divisor evaluator class declaration  --------//
 

include/boost/integer/common_factor_rt.hpp

@@ -4,13 +4,15 @@
 //  use, modify, sell and distribute this software is granted provided this
 //  copyright notice appears in all copies.  This software is provided "as is"
 //  without express or implied warranty, and with no claim as to its suitability
-//  for any purpose. 
+//  for any purpose.
 
 // boostinspect:nolicense (don't complain about the lack of a Boost license)
 // (Paul Moore hasn't been in contact for years, so there's no way to change the
 // license.)
 
-//  See http://www.boost.org for updates, documentation, and revision history. 
+//  See http://www.boost.org for updates, documentation, and revision history.
+//! \file
+//! \brief Evaluate Least Common Multiple at compile-time.
 
 #ifndef BOOST_INTEGER_COMMON_FACTOR_RT_HPP
 #define BOOST_INTEGER_COMMON_FACTOR_RT_HPP
@@ -31,7 +33,7 @@ namespace boost
 {
 namespace integer
 {
-
+// Warning:  this is from 1.58 in namespace boost::interger and no longer in namespace boost::math.
 
 //  Forward declarations for function templates  -----------------------------//
 
@@ -75,6 +77,7 @@ public:
 
 
 //  Implementation details  --------------------------------------------------//
+//! \cond DETAIL
 
 namespace detail
 {
@@ -387,9 +390,13 @@ namespace detail
     }
 
 }  // namespace detail
+//! \endcond // DETAIL
 
-
+//  Greatest common divisor operator() evaluator member function definition  ------------//
-//  Greatest common divisor evaluator member function definition  ------------//
+//! Evaluation operator() for Greatest Common Divisor (GCD) of two arguments.
+//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant
+//! \param a first_argument_type
+//! \param b second_argument_type
 
 template < typename IntegerType >
 inline
@@ -405,7 +412,11 @@ gcd_evaluator<IntegerType>::operator ()
 
 
 //  Least common multiple evaluator member function definition  --------------//
-
+//! Evaluates Least Common Multiplier of two arguments.
+//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant
+//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant
+//! \param a first_argument_type
+//! \param b second_argument_type
 template < typename IntegerType >
 inline
 typename lcm_evaluator<IntegerType>::result_type
@@ -420,6 +431,10 @@ lcm_evaluator<IntegerType>::operator ()
 
 
 //  Greatest common divisor and least common multiple function definitions  --//
+//! Function for Greatest Common Divisor (GCD) of two arguments.
+//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant
+//! \param a first_argument_type
+//! \param b second_argument_type
 
 template < typename IntegerType >
 inline
@@ -435,6 +450,11 @@ gcd
     return solver( a, b );
 }
 
+//! Function for Least Common Multiplier  (LCM) of two arguments.
+//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant
+//! \param a first_argument_type
+//! \param b second_argument_type
+
 template < typename IntegerType >
 inline
 IntegerType

include/boost/integer/integer_log2.hpp

@@ -1,15 +1,18 @@
 // -----------------------------------------------------------
 // integer_log2.hpp
 //
-//   Gives the integer part of the logarithm, in base 2, of a
-// given number. Behavior is undefined if the argument is <= 0.
-//
 //         Copyright (c) 2003-2004, 2008 Gennaro Prota
 //
 // Distributed under the Boost Software License, Version 1.0.
 //    (See accompanying file LICENSE_1_0.txt or copy at
 //          http://www.boost.org/LICENSE_1_0.txt)
 //
+//! \file
+//! \brief  Function integer_log2 gives the integer part of the logarithm, in base 2, of a
+//!  given number (at run-time). Behavior is undefined if the argument is <= 0.
+//
+//! \note For analogous compile-time computation of log2 see static_log2.
+//! \sa http::www.boost.org/doc/integer
 // -----------------------------------------------------------
 
 #ifndef BOOST_INTEGER_INTEGER_LOG2_HPP
@@ -24,6 +27,8 @@
 
 
 namespace boost {
+
+//! \cond DETAIL
  namespace detail {
 
   template <typename T>
@@ -46,7 +51,6 @@ namespace boost {
   }
 
 
-
   // helper to find the maximum power of two
   // less than p (more involved than necessary,
   // to avoid PTS)
@@ -82,9 +86,8 @@ namespace boost {
 #endif
 
   };
-
  } // detail
-
+//! \endcond // DETAIL
 
  // ---------
  // integer_log2
@@ -104,9 +107,6 @@ namespace boost {
  }
 
 
-
 }
 
-
+#endif // BOOST_INTEGER_INTEGER_LOG2_HPP  include guard
-
-#endif // include guard

include/boost/integer/integer_mask.hpp

@@ -5,7 +5,10 @@
 //  accompanying file LICENSE_1_0.txt or copy at
 //  http://www.boost.org/LICENSE_1_0.txt)
 
-//  See http://www.boost.org for updates, documentation, and revision history. 
+//  See http://www.boost.org for updates, documentation, and revision history.
+
+//! \file
+//! \brief Compile-time integer mask evaluation.
 
 #ifndef BOOST_INTEGER_INTEGER_MASK_HPP
 #define BOOST_INTEGER_INTEGER_MASK_HPP
@@ -35,7 +38,6 @@
 namespace boost
 {
 
-
 //  Specified single-bit mask class declaration  -----------------------------//
 //  (Lowest bit starts counting at 0.)
 

include/boost/integer/static_log2.hpp

@@ -10,6 +10,11 @@
 //
 //         ---------------------------------------------------
 //       See http://www.boost.org/libs/integer for documentation.
+
+//! \file
+//! \brief Compile-time calculation of integer part of the logarithm, in base 2, of a given number.
+//! \note For a run-time calculation of log2, see function integer_log2 at integer_log2.hpp.
+
 // ------------------------------------------------------------------------- //
 
 
@@ -20,6 +25,8 @@
 
 namespace boost {
 
+  //! \cond DETAIL
+
  namespace detail {
 
      namespace static_log2_impl {
@@ -99,8 +106,7 @@ namespace boost {
 
      }
  } // detail
-
+//! \endcond  // DETAIL
-
 
  // --------------------------------------
  // static_log2<x>
@@ -120,7 +126,7 @@ namespace boost {
  template <>
  struct static_log2<0> { };
 
-}
+} // namespace boost
 
 
 

include/boost/integer/static_min_max.hpp

@@ -5,7 +5,9 @@
 //  accompanying file LICENSE_1_0.txt or copy at
 //  http://www.boost.org/LICENSE_1_0.txt)
 
-//  See http://www.boost.org for updates, documentation, and revision history. 
+//  See http://www.boost.org for updates, documentation, and revision history.
+//! \file
+//! \brief Compile-time evaluation of extrema: minimum or maximum of two values, signed or unsigned.
 
 #ifndef BOOST_INTEGER_STATIC_MIN_MAX_HPP
 #define BOOST_INTEGER_STATIC_MIN_MAX_HPP

include/boost/integer_fwd.hpp

@@ -5,6 +5,8 @@
 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 //  See http://www.boost.org/libs/integer for documentation.
+//! \file
+//! \brief Include all Boost.Integer files.
 
 #ifndef BOOST_INTEGER_FWD_HPP
 #define BOOST_INTEGER_FWD_HPP

include/boost/integer_traits.hpp

@@ -8,10 +8,15 @@
  * $Id$
  *
  * Idea by Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers
+
  */
 
 //  See http://www.boost.org/libs/integer for documentation.
 
+//! \file
+//! \brief integer traits
+//! \sa http://www.boost.org/libs/integer
+
 
 #ifndef BOOST_INTEGER_TRAITS_HPP
 #define BOOST_INTEGER_TRAITS_HPP
@@ -47,6 +52,7 @@ public:
   BOOST_STATIC_CONSTANT(bool, is_integral = false);
 };
 
+//! \cond DETAIL
 namespace detail {
 template<class T, T min_val, T max_val>
 class integer_traits_base
@@ -70,6 +76,7 @@ const T integer_traits_base<T, min_val, max_val>::const_max;
 #endif
 
 } // namespace detail
+//! \endcond // DETAIL
 
 template<>
 class integer_traits<bool>

test/integer_test.cpp

@@ -69,7 +69,7 @@ void do_test_exact(boost::mpl::true_ const&)
 template <int Bits>
 void do_test_exact(boost::mpl::false_ const&)
 {
-   // Nothing to do, type does not have an ::extact member.
+   // Nothing to do, type does not have an ::exact member.
 }
 
 template <int Bits>