[Boost-commit] svn:boost r71507 - in sandbox/tools/quick_auto_dox_index/boost: . quick_auto_dox_index quick_auto_dox_index/detail

Subject: [Boost-commit] svn:boost r71507 - in sandbox/tools/quick_auto_dox_index/boost: . quick_auto_dox_index quick_auto_dox_index/detail
From: pbristow_at_[hidden]
Date: 2011-04-26 11:53:20

Author: pbristow
Date: 2011-04-26 11:53:19 EDT (Tue, 26 Apr 2011)
New Revision: 71507
URL: http://svn.boost.org/trac/boost/changeset/71507

Log:
First public view.  Still needs plenty more work.
Added:
   sandbox/tools/quick_auto_dox_index/boost/
   sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/
   sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/detail/
   sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/detail/FP_compare.hpp   (contents, props changed)
   sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/quick_auto_dox_index.hpp   (contents, props changed)

Added: sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/detail/FP_compare.hpp
==============================================================================
--- (empty file)
+++ sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/detail/FP_compare.hpp	2011-04-26 11:53:19 EDT (Tue, 26 Apr 2011)
@@ -0,0 +1,249 @@
+/*! \file FP_compare.hpp
+    \brief Two types of floating-point comparison "Very close" and "Close enough" to a chosen tolerance.
+    \details
+      Derived from Boost.Test Copyright Gennadiy Rozental 2001-2007.
+      See http://www.boost.org/libs/test for the Boost.Test library home page.
+      Deliberately removed any treatment of percent to avoid further potential confusion!
+    \date Mar 2009
+    \author Paul A. Bristow
+*/
+
+//  Copyright Paul A. Bristow 2008, 2009
+
+//  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)
+
+#ifndef BOOST_FLOATING_POINT_COMPARISON_HPP
+#define BOOST_FLOATING_POINT_COMPARISON_HPP
+
+#include <boost/limits.hpp>  // using std::numeric_limits
+#include <boost/math/tools/precision.hpp> // using max_value, min_value & epsilon for floating_point type.
+
+//namespace boost
+//{
+//  namespace math
+//  {
+
+// Check two floating-point values are close within a chosen tolerance.
+template<typename FPT> class close_to; // Default = double.
+
+// Check floating-point value is smaller than a chosen small value.
+template<typename FPT> class smallest; // Default = double.
+
+enum floating_point_comparison_type
+{ /*! \enum floating_point_comparison_type
+   \brief Two types of floating-point comparison "Very close" and "Close enough".
+   \details equations in Douglas E. Knuth, Seminumerical algorithms (3rd Ed) section 4.2.4, Vol II,
+    pp 213-225, Addison-Wesley, 1997, ISBN: 0201896842.\n
+    Strong requires closeness relative to \b both values being compared,
+    Weak only requires only closeness relative to \b either \b one value.
+  */
+  FPC_STRONG, //!< "Very close"   - Knuth equation 1 (the default).
+  FPC_WEAK    //!< "Close enough" - Knuth equation 2.
+};
+
+// GNU int gsl_fcmp (double x, double y, double epsilon) provides similar function.
+// fcmp also provides a C implementation at https://sourceforge.net/projects/fcmp/
+// For IEEE floating-point types, some speedups are possible, for example see:
+// Taming the Floating-point Beast, Chris Lomont
+// www.lomont.org/Math/Papers/2005/CompareFloat.pdf
+// Alberto Squassabia, Comparing Floats:
+// How to determine if Floating-point quantities are close enough
+// once a tolerance has been reached:  C++ report March 2000.
+// Gennadiy Rozental, Floating_point comparison algorithms,
+// www.boost.org/libs/test/doc/components/test_tools/floating_point_comparison.html
+// Comparison of Floating Point Numbers, Matthias Ruppwww.mrupp.info/Data/2007floatingcomp.pdf, July 2007.
+// The pitfalls of verifying floating-point computations, David Monniaux
+// CNRS Ecole normale superieure, 1 Feb 2008, http://arxiv.org/abs/cs/0701192v4
+// submitted to ACM TOPLAS.
+
+// \tparam FPT is Floating-Point Type: float, double, long double, or User-Defined like NTL quad_float or RR.
+// from boost/math/tools/precision.hpp
+template <class FPT> FPT max_value(FPT); //!< maximum value for floating-point type T.
+template <class FPT> FPT min_value(FPT); //!< minimum value for floating-point type T.
+template <class FPT> FPT epsilon(FPT); //!< epsilon for type T (about 1e-16 for double)
+
+template<typename FPT> FPT
+fpt_abs(FPT arg)
+{ //! abs function (just in case abs is not defined for a user-defined FPT).
+  return arg <static_cast<FPT>(0) ? -arg : arg;
+}
+
+template<typename FPT> FPT
+safe_fpt_division(FPT f1, FPT f2)
+{ //! Division safe from underflow and overflow. (Both f1 and f2 must be unsigned here).
+  if( (f2 < static_cast<FPT>(1))  && (f1 > f2 * boost::math::tools::max_value<FPT>()) )
+  { // Avoid overflow.
+    return boost::math::tools::max_value<FPT>();
+  }
+  if( (f1 == static_cast<FPT>(0))
+    || ((f2 > static_cast<FPT>(1)) && (f1 < f2 * boost::math::tools::min_value<FPT>()) )
+    )
+  {  // Avoid underflow.
+    return static_cast<FPT>(0);
+  }
+  return f1 / f2;
+} // safe_fpt_division(FPT f1, FPT f2)
+
+template<typename FPT = double> //! \tparam FPT floating-point type.
+class close_to
+{ /*!
+   \class close_to
+   \brief Test if two floating-point values are close within a chosen tolerance.
+   \details Close can be one of two types of floating-point comparison "Very close" and "Close enough".
+    equations in Dougles E. Knuth, Seminumerical algorithms (3rd Ed) section 4.2.4, Vol II,
+    pp 213-225, Addison-Wesley, 1997, ISBN: 0201896842.
+    Strong requires closeness relative to BOTH values begin compared,
+    Weak only requires only closeness to EITHER ONE value.
+
+  */
+public:
+  //! Constructor for close_to from tolerance and strength. (By design, percent is NOT implemented).
+  template<typename FPT>
+  explicit close_to(FPT tolerance, //!< Fractional tolerance.
+    floating_point_comparison_type fpc_type = FPC_STRONG) //!< strong requires closeness relative to both values.
+  :
+    fraction_tolerance_(tolerance),
+      strong_or_weak_(fpc_type)
+  { // Fraction.
+    // Check that tolerance isn't negative - which doesn't make sense,
+    // and can be assumed to be a programmer error?
+    BOOST_ASSERT(tolerance >= static_cast<FPT>(0));
+  }
+
+  close_to()
+  :
+  fraction_tolerance_(2 * boost::math::tools::epsilon<FPT>()),
+    strong_or_weak_(FPC_STRONG)
+  { /*! Default is two epsilon for the FPT.\n
+        Note that some user-defined floating-point types may not specialize std::numeric_limits<FPT>::epsilon()
+        so it is convenient to use boost::math::tools::epsilon<FPT>(); instead.
+     */
+
+  }
+
+  bool operator()(FPT left, FPT right) const
+  { //! \brief Test if two floating-point values are close within a chosen tolerance.
+    //! \details Tolerance can be interpreted as Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
+
+    FPT diff = fpt_abs(left - right);
+    FPT d1   = safe_fpt_division(diff, fpt_abs(right));
+    FPT d2   = safe_fpt_division(diff, fpt_abs(left));
+
+    return strong_or_weak_
+      ? ((d1 <= fraction_tolerance_) && (d2 <= fraction_tolerance_)) // Strong.
+      : ((d1 <= fraction_tolerance_) || (d2 <= fraction_tolerance_)); // Weak.
+  }
+
+  FPT size()
+  { //! \return the chosen tolerance, as a \b fraction (not a percentage).
+    return fraction_tolerance_;
+  }
+
+  floating_point_comparison_type strength()
+  { //! \return strength of comparison, Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
+    return strong_or_weak_;
+  }
+
+private:
+    FPT fraction_tolerance_; //!< tolerance as a fraction.
+    floating_point_comparison_type strong_or_weak_;  //!< Knuth's  "Very close" (equation 1), the default, or "Close enough" (equation 2).
+
+}; // class close_to
+
+template<typename FPT = double>
+class smallest
+{ /*! \class smallest
+      \brief Check floating-point value is smaller than a chosen small value,
+         default is twice min_value() for the floating-point type FPT.
+      \details
+       It is somewhat common for beginners to add a comparison check to 0 before
+       computing a division, in order to avoid possible division-by-zero exceptions or
+       the generation of infinite results.\n
+       A first objection to this practise is that, anyway,
+       computing 1/x for x very close to zero will generate very large numbers
+       that will most probably result in overflows later.\n
+       Another objection, which few programmers know about and that we wish to draw attention
+       to, is that it may actually fail to work, depending on what the compiler
+       does, that is, the program may actually test that x == 0, then, further down,
+       find that x = 0 without any apparent change to x!\n
+       David Monniaux, http://arxiv.org/abs/cs/0701192v4.
+       \tparam FPT A floating-point type, float, double, long double or user-defined like NTL quad_float or RR.
+   */
+
+public:
+  template<typename FPT>
+  explicit smallest(FPT s)
+  :
+  smallest_(s)
+  { /*! Constructor with user defined value of smallest, for example 10 * min_value<FPT>.
+        Note that some user-defined floating-point types may not specialize std::numeric_limits<FPT>::min_value()
+        so it is convenient to use boost::math::tools::min_value<FPT>(); instead.
+    */
+  }
+
+  smallest()
+  :
+  smallest_(2 * boost::math::tools::min_value<FPT>())
+  { /*! Default Constructor with smallest_ =  2. * boost::math::tools::min_value<double>();\n
+       multiplier m = 2 (must be integer or static_cast<FPT>())
+       is chosen to allow for a few bits of computation error.\n
+       Pessimistic multiplier is the number of arithmetic operations,
+       assuming every operation causes a 1 least significant bit error,
+       but a more realistic average might be half this.
+     */
+  }
+
+  bool operator()(FPT fp_value, FPT s)
+  { //! True if value is smaller than a smallest value s.
+    if (fpt_abs(fp_value) == static_cast<FPT>(0))
+    { // Test for zero first in case FPT is actually an integer type zero,
+      // when the comparison < below would fail because
+      // smallest_ could become zero when min_value converts to integer.
+      return true;
+    }
+    return fpt_abs(fp_value) < fpt_abs(s);
+  } // bool operator()
+
+  bool operator()(FPT fp_value)
+  { //! True if value is smaller than chosen smallest value.
+    if (fpt_abs(fp_value) == static_cast<FPT>(0))
+    { // Test for zero first in case FPT is actually an integer type,
+      // when the comparison < below would fail because smallest could become zero.
+      return true;
+    }
+    return fpt_abs(fp_value) < fpt_abs(smallest_);
+  } // bool operator()
+
+  FPT size()
+  { //! \return chosen smallest value that will be counted as effectively zero.
+    return smallest_;
+  }
+
+private:
+  FPT smallest_; //!< Chosen smallest value that will be counted as effectively zero.
+}; // class smallest
+
+// Define two convenience typedefs.
+
+typedef smallest<double> tiny;
+/*!
+  \typedef tiny
+  \brief Allow tiny as a shorthand for twice the double min_value 4.45e-308.
+  \details Since double and the default smallest value 2 * std::numeric_limits<double>::min_value() = 2 * 2.22507e-308 + 4.45015e-308
+  is a very common requirement, provide an convenience alias for this.
+*/
+
+/*!
+  \typedef neareq
+  \brief Allow neareq as a shorthand for twice double epsilon = 4.44e-16
+  \details Since double and the default close_to value 2 * epsilon =  std::numeric_limits<double>::epsilon = 2 * 2.220446e-016 = 4.440892e-016
+  is a very common requirement, provide an convenience alias for this.
+*/
+typedef close_to<double> neareq;
+
+ // namespace math
+ // namespace boost
+
+#endif // BOOST_FLOATING_POINT_COMPARISON_HPP

Added: sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/quick_auto_dox_index.hpp
==============================================================================
--- (empty file)
+++ sandbox/tools/quick_auto_dox_index/boost/quick_auto_dox_index/quick_auto_dox_index.hpp	2011-04-26 11:53:19 EDT (Tue, 26 Apr 2011)
@@ -0,0 +1,124 @@
+/*!
+  \file quick_auto_dox_index.hpp
+  \brief Template for documentation.
+  \details Example file for creating Boost documentation using Quickbook, Doxygen and Auto-Indexing.
+    Example code with comment taken from /doxygen/html/docblocks.html using Boost naming conventions.
+    \n
+    The style of this example takes a lot of lines, so other Boost-style examples are much more compact.
+    They do rely on syntax coloring to make the comments stand clear
+    and not obscure the real C++ code.
+
+  \date Mar 2011
+  \author  Paul A. Bristow
+*/
+
+// Copyright Paul A. Bristow 2011
+
+// 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)
+
+#ifndef BOOST_QUICK_AUTO_DOX_INDEX_HPP
+#define BOOST_QUICK_AUTO_DOX_INDEX_HPP
+
+/*! \mainpage QuickBook Auto Doxygen Indexed Main page.
+This is the standalone Doxygen front page of the QuickBook Auto Doxygen Indexed
+example of producing Boost documentation.
+
+\n It is redundant for production of html and pdf output,
+but useful to allow just Doxygen manuals (no Quickbook text or indexing).
+
+Standalone Doxygen can provide a more convenient compact index of
+the classes, files, namespaces and functions.
+They provide the Doxygen comments, but not any text from Quickbook.
+
+These manuals are quickly produced using the Doxywizard GUI frontend.
+A suitable doxyfile holding the list of files to include etc
+is conveniently placed in a /doc/doxygen sub-folder.
+Selecting this as the working directory from which doxygen will run as Step 1,
+and the run tab, and "run doxygen' in Step 2 should generate
+an html with index.html in the /doxygen sub-folder.
+
+The mainpage should give a pointer to the full html and/or pdf versions
+that provide the full Quickbook generated information.
+
+I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/index.html
+QuickBook Auto Doxygen Indexed Manual
+
+*/
+
+ //! \brief A test class - a comment description that preceeds the class.
+class test
+{ /*! \details \class test More on a class by comment that is tucked in under the class (to reduce the line count).
+  BUT you must explicitly link to the class or it will be applied to the next member.
+  Using a < doesn't work for classes as it does for members.
+*/
+  public:
+    //! Example of documenting an enum.
+    /*! More detailed enum description.
+       This description needs more than one line,
+       so convenient to use C style comment markers.
+    */
+    enum test_enum {
+                 test_enum_val1, //!< Enum value TVal1 (Note the < to link to the same line).
+                 test_enum_val2, //!< Enum value TVal2. (Using C++ // comment markers, and < to link to the same line.
+                 test_enum_val3  /*!< Enum value TVal3. (using C style comment markers).*/
+               };
+
+    //! A constructor.
+    /*!
+      A more elaborate description of the constructor.
+    */
+    test();
+
+    //! A destructor.
+    /*!
+      A more elaborate description of the destructor.
+      \pre No preconditions.
+      \post A test object constructed, with no side effects.
+      \warning This descructor may blow up?
+    */
+   ~test();
+
+    //! A normal member function taking two arguments and returning an integer value.
+    /*!
+      \param a an integer argument.
+      \param s a constant character pointer.
+      \returns The test result.
+      \pre No preconditions.
+      \post No side effects.
+      \sa Test(), ~Test(), testMeToo() and publicVar()
+    */
+    int test_me(int a, const char *s);
+
+    /*! A pure virtual member with descriptions of parameters.
+        And a 'see also' reference to another version of the function.
+
+      \see test_me()
+      \deprecated Will be removed in the next but one version.  Use test_me() instead.
+      \param c1 the first argument.
+      \param c2 the second argument.
+      \returns The test result.
+
+    */
+    virtual void test_me_too(char c1, char c2) = 0;
+
+    //! A public variable.
+    /*!
+      Details about the variable.
+    */
+    int public_var;
+
+    //! A function variable.
+    /*!
+      Details about what the function does.
+      \remark This is an implementation detail and not for user code.
+      \param a 1st Selector.
+      \param b 2nd Selector.
+      \returns result of calling handler.
+    */
+    int (*handler)(int a,int b);
+}; // class test
+
+#endif // BOOST_QUICK_AUTO_DOX_INDEX_HPP