[Boost-commit] svn:boost r6994

From: hervebronnimann_at_[hidden]
Date: 2007-06-12 01:55:14

Author: hervebronnimann
Date: 2007-06-12 01:55:14 EDT (Tue, 12 Jun 2007)
New Revision: 6994
URL: http://svn.boost.org/trac/boost/changeset/6994

Log:
New-style documentation (so much more readable).  Proposition to come by email.

Text files modified: 
   sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/backward_hds_concept.hpp |   334 +++++++++++++++++++++------------------ 
   sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/forward_hds_concept.hpp  |   334 +++++++++++++++++++++------------------ 
   sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/hds_concept.hpp          |   259 +++++++++++++++++-------------          
   3 files changed, 497 insertions(+), 430 deletions(-)

Modified: sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/backward_hds_concept.hpp
==============================================================================
--- sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/backward_hds_concept.hpp	(original)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/backward_hds_concept.hpp	2007-06-12 01:55:14 EDT (Tue, 12 Jun 2007)
@@ -1,166 +1,186 @@
-/**
- * @file backward_hds_concept.hpp
- *
- * @brief Backward HDS concept definition.
- *
- * @par Definition
- * This concept refines the HDSConcept, and specifies additional backward
- * category to iterate over the HDS data structure, which means clockwise 
- * movement around the facet and counter clockwise movement around the
- * vertex. Possible backward categories are prev_in_facet, 
- * prev_at_source, and prev_at_target. Once one of these categories 
- * are given all others can be accessed with the help of the opposite of a 
- * halfedge.
- *
- * @par Refinement of
- *  - HDSConcept
- *
- * @par Notation
- *  - HDS        A type that is a model of BackwardHDSConcept
- *  - hds        A non-modifiable instance of HDS
- *  - h,g        Halfedge descriptors, of type X::halfedge_descriptor
- *
- * @par Associated types
- *  - hds_traits<HDS>::halfedge_descriptor: must be DefaultConstructible and 
- *                         CopyConstructible, EqualityComparable, Assignable.
- *  - hds_traits<HDS>::traversal_category:  must be convertible to 
- *                           hds_traits<HDS>::backward_traversal_tag.
- *  - hds_traits<HDS>::backward_category:  Defines the pointer type for 
- *                                                   backward iteration.
- *
- * @par Definitions
- *  - @e halfedge @e descriptor is a type that contains information to access 
- *                                                               the halfedge.
- *  - @e traversal @e category is a type that contains information about the 
- *    direction of the traversal, which is forward, backward or bidirectional.
- *    For backward hds concept, it has to be convertible to  
- *    hds_traits<HDS>::backward_traversal_tag.
- *  - @e backward @e category defines the type of the backward iteration. 
- *
- * @par Valid Expressions
- *   - prev_in_facet(hds,h) : Must return a value assignable to h.
- *   - prev_at_source(hds,h) : Must return a value assignable to h.
- *   - prev_at_target(hds,h) : Must return a value assignable to h.
- *
- * @par Expression Semantics
- *   - prev_in_facet(hds,h) : returns an halfedge descriptor to next halfedge 
- *                                in clockwise order around the facet.
- *   - prev_at_source(hds,h) : returns an halfedge descriptor to next halfedge 
- *                          in counter clockwise order around the source vertex.
- *   - prev_at_target(hds,h) : returns an halfedge descriptor to next halfedge 
- *                          in counter clockwise order around the target vertex.
- *
- * @par Complexity guarantees
- *  - prev_in_facet(hds,h) : Amortized constant time
- *  - prev_at_source(hds,h) : Amortized constant time
- *  - prev_at_target(hds,h) : Amortized constant time
- *
- * @par Invariants 
- *   - prev_in_facet(hds,h) == prev_at_target(opposite(hds,h)) 
- *                          == opposite(prev_at_source(hds,h))
- *   - prev_at_source(hds,h) == opposite(prev_in_facet(hds,h)) 
- *                           == opposite(prev_at_target(opposite(hds,h)))
- *   - prev_at_target(hds,h) == prev_in_facet(opposite(hds,h)) 
- *                           == opposite(prev_at_source(opposite(hds,h)))
- *
- * @par Concept-checking class
- * \code
- * template <class HDS> 
- * struct BackwardHDSConcept {
- *   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
- *   typedef typename hds_traits<HDS>::traversal_category traversal_category;
- *   typedef typename hds_traits<HDS>::backward_category backward_category;
- *    void constraints() {
- *       using namespace boost;
- *       function_requires<HDSConcept<HDS> >();
- *       function_requires<ConvertibleConcept<traversal_category,
- *                                                backward_traversal_tag> >();  
- *       const bool is_valid_storage_tag =
- *          is_convertible<backward_category,prev_at_source_tag>::value ||
- *          is_convertible<backward_category,prev_at_target_tag>::value ||
- *          is_convertible<backward_category,prev_in_facet_tag>::value;
- *       BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
- *       // Error message could be improved
- *       h = prev_in_facet(hds,h);
- *       h = prev_at_source(hds,h);
- *       h = prev_at_target(hds,h);
- *       const_constraints(hds);
- *    }
- *    void const_constraints(HDS const& hds){
- *       h = prev_in_facet(hds,h);
- *       h = prev_at_source(hds,h);
- *       h = prev_at_target(hds,h);
- *    }
- *    BackwardHDS hds;
- *    halfedge_descriptor h;
- *    halfedge_descriptor g;
- * };
- * \endcode
- */
+//backward_hds_concept.hpp  -*- C++ -*-
+//
+//@PURPOSE: Proviade 'BackwardHDS' concept definition and concept-checking class.
+//
+//@DESCRIPTION: This file provides a single class template that,
+// when used with the following concept-checking utilities:
+//..
+//  boost::function_requires<BackwardHDSConcept<HDS> >();
+//..
+// inside a function body, or
+//..
+//  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, BackwardHDSConcept);
+//..
+// inside a class body, checks whether the type given as template
+// argument is a model of the HDS concept described on the page
+// [backwardhds].
+//
+//@CONCEPT: [backwardhds] Backward HDS concept
+//
+///Definition
+///----------
+// This concept refines the 'HDSConcept', and specifies additional backward
+// category to iterate over the 'HDS' data structure, which means clockwise 
+// movement around the facet and counter clockwise movement around the
+// vertex. Possible backward categories are 'prev_in_facet', 
+// 'prev_at_source', and 'prev_at_target'. Once one of these categories 
+// are given all others can be accessed with the help of the 'opposite' of a 
+// halfedge (see the section "Invariants" below for the algebraic relations
+// that must hold).
+//
+///Refinement of
+///-------------
+//  - 'HDSConcept'
+//
+///Notation
+///--------
+//  - 'HDS'    A type that is a model of 'BackwardHDSConcept'
+//  - 'hds'    A non-modifiable instance of 'HDS'
+//  - 'h','g'  Halfedge descriptors, of type 'hds_traits<HDS>::halfedge_descriptor'
+//
+///Associated types
+///----------------
+//  - 'hds_traits<HDS>::halfedge_descriptor': from 'HDSConcept'.
+//  - 'hds_traits<HDS>::traversal_category':  from 'HDSConcept', with
+//     additional requirement that this type must be convertible to
+//     'hdstl::backward_traversal_tag'.
+//  - 'hds_traits<HDS>::backward_category':   defines the pointer type for 
+//     backward iteration.
+//
+///Definitions
+///-----------
+//  - 'halfedge_descriptor' is a type that contains information to access 
+//     the halfedge.  (See the 'HDS' concept or a full definition.)
+//  - 'traversal_category' is a type that contains information about the 
+//     direction of the traversal, which is forward, backward or bidirectional.
+//     For this 'BackwardHDS' concept, the 'traversal_category' has to be convertible to  
+//     the 'hdstl::backward_traversal_tag' type defined in '<boost/hdstl.hpp>'.
+//  - 'backward_category' defines the primary accessor of the backward
+//     information for use by algorithms which desire the most direct access. 
+//
+///Valid Expressions
+///-----------------
+// In addition to the valid expressions of the 'HDS' concept:
+//   - 'prev_in_facet(hds,h)' must return a value assignable to h.
+//   - 'prev_at_source(hds,h)' must return a value assignable to h.
+//   - 'prev_at_target(hds,h)' must return a value assignable to h.
+//
+///Expression Semantics
+///--------------------
+// In addition to the expression semantics of the 'HDS' concept:
+//   - 'prev_in_facet(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' in the adjacent facet cycle, when facet cycles are
+//      oriented in counter-clockwise order.
+//   - 'prev_at_source(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' around the source vertex of 'h', when halfedges are
+//      ordered around a given vertex in clockwise order.
+//   - 'prev_at_target(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' around the target vertex of 'h', when halfedges are
+//      ordered around a given vertex in clockwise order.
+//
+///Complexity guarantees
+///---------------------
+//  - 'prev_in_facet(hds,h)': amortized constant time.
+//  - 'prev_at_source(hds,h)': amortized constant time.
+//  - 'prev_at_target(hds,h)': amortized constant time.
+//
+///Invariants 
+///----------
+// The backward halfedge accessors are linked via the algebraic relations:
+//   - 'prev_in_facet(hds,h)'  == 'prev_at_target(opposite(hds,h))' 
+//                             == 'opposite(prev_at_source(hds,h))'
+//   - 'prev_at_source(hds,h)' == 'opposite(prev_in_facet(hds,h))' 
+//                             == 'opposite(prev_at_target(opposite(hds,h)))'
+//   - 'prev_at_target(hds,h)' == 'prev_in_facet(opposite(hds,h))'
+//                             == 'opposite(prev_at_source(opposite(hds,h)))'
+//
+///Concept-checking class
+///----------------------
+//..
+// template <class HDS> 
+// struct BackwardHDSConcept {
+//   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+//   typedef typename hds_traits<HDS>::traversal_category traversal_category;
+//   typedef typename hds_traits<HDS>::backward_category backward_category;
+//    void constraints() {
+//       using namespace boost;
+//       function_requires<HDSConcept<HDS> >();
+//       function_requires<ConvertibleConcept<traversal_category,
+//                                        hdstl::backward_traversal_tag> >();  
+//       const bool is_valid_storage_tag =
+//          is_convertible<backward_category,prev_at_source_tag>::value ||
+//          is_convertible<backward_category,prev_at_target_tag>::value ||
+//          is_convertible<backward_category,prev_in_facet_tag>::value;
+//       BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
+//
+//       const_constraints(hds);
+//    }
+//    void const_constraints(HDS const& hds){
+//       h = prev_in_facet(hds,h);
+//       h = prev_at_source(hds,h);
+//       h = prev_at_target(hds,h);
+//    }
+//    BackwardHDS hds;
+//    halfedge_descriptor h;
+//    halfedge_descriptor g;
+// };
+//..
 
 #ifdef BOOST_HDSTL_CONCEPTS_BACKWARDHDSCONCEPT_HPP
 #define BOOST_HDSTL_CONCEPTS_BACKWARDHDSCONCEPT_HPP 1
 
 namespace hdstl{
 namespace concepts{
-   /**
-    * @class BackwardHDSConcept
-    *
-    * @brief Backward HDS concept checking class.
-    * 
-    * @par Definition
-    * This class provides a concept checking class for the BackwardHDSConcept,
-    * i.e., using the statement boost::function_requires<BackwardHDSConcept<HDS>
-    * >() inside a function body, or BOOST_CLASS_REQUIRE(HDS, boost::hdstl,
-    * BackwardHDSConcept) inside a class definition body, should trigger a
-    * compile-time error if the type HDS does not model the BackwardHDSConcept.
-    */
-   template <class HDS> 
-   struct BackwardHDSConcept {
-      //@{
-      /** @name Required types: 
-       * The specialization of hds_traits<HDS> must have
-       * the required types below
-       */
-      typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
-      typedef typename hds_traits<HDS>::traversal_category traversal_category;
-      typedef typename hds_traits<HDS>::backward_category backward_category;
-      //@}
-
-      /**
-       * @name Defined constraints:
-       */
-      void constraints() {
-         using namespace boost;
-
-         function_requires<HDSConcept<HDS> >();
-         function_requires<ConvertibleConcept<traversal_category,
-                                                  backward_traversal_tag> >();  
-         const bool is_valid_storage_tag =
-            is_convertible<backward_category,prev_at_source_tag>::value ||
-            is_convertible<backward_category,prev_at_target_tag>::value ||
-            is_convertible<backward_category,prev_in_facet_tag>::value;
-         BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
-         // Error message could be improved
-
-         h = prev_in_facet(hds,h);
-         h = prev_at_source(hds,h);
-         h = prev_at_target(hds,h);
-         const_constraints(hds);
-      }
-      /**
-       * Defined const constraints
-       */
-      void const_constraints(HDS const& hds){
-         h = prev_in_facet(hds,h);
-         h = prev_at_source(hds,h);
-         h = prev_at_target(hds,h);
-      }
-      
-      BackwardHDS hds;
-      halfedge_descriptor h;
-      halfedge_descriptor g;
-   };
+
+    template <class HDS> 
+    struct BackwardHDSConcept {
+        // This class provides a concept checking class for the BackwardHDSConcept,
+        // i.e., using the statement
+        //..
+        //  boost::function_requires<BackwardHDSConcept<HDS>()
+        //..
+        // inside a function body, or
+        //..
+        //  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, BackwardHDSConcept);
+        //..
+        // inside a class definition body, should trigger a compile-time error
+        // if the type HDS does not model the 'BackwardHDSConcept'.
+
+        // TYPES
+        typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+        typedef typename hds_traits<HDS>::traversal_category traversal_category;
+        typedef typename hds_traits<HDS>::backward_category backward_category;
+
+        // MANIPULATORS
+        void constraints() {
+            using namespace boost;
+
+            function_requires<HDSConcept<HDS> >();
+            function_requires<ConvertibleConcept<traversal_category,
+            backward_traversal_tag> >();  
+            const bool is_valid_storage_tag =
+                    is_convertible<backward_category,prev_at_source_tag>::value ||
+                    is_convertible<backward_category,prev_at_target_tag>::value ||
+                    is_convertible<backward_category,prev_in_facet_tag>::value;
+            BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
+
+            const_constraints(hds);
+        }
+
+        // ACCESSORS
+        void const_constraints(HDS const& hds){
+            h = prev_in_facet(hds,h);
+            h = prev_at_source(hds,h);
+            h = prev_at_target(hds,h);
+        }
+
+      private:
+        // DATA
+        BackwardHDS hds;        // a halfedge data structure object
+        halfedge_descriptor h;  // a halfedge descriptor
+        halfedge_descriptor g;  // another halfedge descriptor
+    };
+
 }  // close namespace concepts
 }  // close namespace hdstl
 

Modified: sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/forward_hds_concept.hpp
==============================================================================
--- sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/forward_hds_concept.hpp	(original)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/forward_hds_concept.hpp	2007-06-12 01:55:14 EDT (Tue, 12 Jun 2007)
@@ -1,166 +1,186 @@
-/**
- * @file forward_hds_concept.hpp
- *
- * @brief Forward HDS concept definition.
- *
- * @par Definition
- * This concept refines the HDSConcept, and specifies additional forward
- * category to iterate over the HDS data structure, which means counter
- * clockwise movement around the facet and clockwise movement around the
- * vertex. Possible forward categories are next_in_facet, 
- * next_at_source, and next_at_target. Once one of these categories 
- * are given all others can be accessed with the help of the opposite of a 
- * halfedge.
- *
- * @par Refinement of
- *  - HDSConcept
- *
- * @par Notation
- *  - HDS        A type that is a model of ForwardHDSConcept
- *  - hds        A non-modifiable instance of HDS
- *  - h,g        Halfedge descriptors, of type X::halfedge_descriptor
- *
- * @par Associated types
- *  - hds_traits<HDS>::halfedge_descriptor: must be DefaultConstructible and 
- *                         CopyConstructible, EqualityComparable, Assignable.
- *  - hds_traits<HDS>::traversal_category:  must be convertible to 
- *                           hds_traits<HDS>::forward_traversal_tag.
- *  - hds_traits<HDS>::forward_category:  Defines the pointer type for forward 
- *                                                                   iteration.
- *
- * @par Definitions
- *  - @e halfedge @e descriptor is a type that contains information to access 
- *                                                               the halfedge.
- *  - @e traversal @e category is a type that contains information about the 
- *    direction of the traversal, which is forward, backward or bidirectional.
- *    For forward hds concept, it has to be convertible to  
- *    hds_traits<HDS>::forward_traversal_tag.
- *  - @e forward @e category defines the type of the forward iteration. 
- *
- * @par Valid Expressions
- *   - next_in_facet(hds,h) : Must return a value assignable to h.
- *   - next_at_source(hds,h) : Must return a value assignable to h.
- *   - next_at_target(hds,h) : Must return a value assignable to h.
- *
- * @par Expression Semantics
- *   - next_in_facet(hds,h) : returns an halfedge descriptor to next halfedge 
- *                                in counter clockwise order around the facet.
- *   - next_at_source(hds,h) : returns an halfedge descriptor to next halfedge 
- *                                in clockwise order around the source vertex.
- *   - next_at_target(hds,h) : returns an halfedge descriptor to next halfedge 
- *                                in clockwise order around the target vertex.
- *
- * @par Complexity guarantees
- *  - next_in_facet(hds,h) : Amortized constant time
- *  - next_at_source(hds,h) : Amortized constant time
- *  - next_at_target(hds,h) : Amortized constant time
- *
- * @par Invariants 
- *   - next_in_facet(hds,h) == next_at_source(opposite(hds,h)) 
- *                          == opposite(next_at_target(hds,h))
- *   - next_at_source(hds,h) == next_in_facet(opposite(hds,h)) 
- *                           == opposite(next_at_target(opposite(hds,h)))
- *   - next_at_target(hds,h) == opposite(next_in_facet(hds,h)) 
- *                           == opposite(next_at_source(opposite(hds,h)))
- *
- * @par Concept-checking class
- * \code
- * template <class HDS> 
- * struct ForwardHDSConcept {
- *   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
- *   typedef typename hds_traits<HDS>::traversal_category traversal_category;
- *   typedef typename hds_traits<HDS>::forward_category forward_category;
- *    void constraints() {
- *       using namespace boost;
- *       function_requires<HDSConcept<HDS> >();
- *       function_requires<ConvertibleConcept<traversal_category
- *                                                ,forward_traversal_tag> >();  
- *       const bool is_valid_storage_tag =
- *          is_convertible<forward_category,next_at_source_tag>::value ||
- *          is_convertible<forward_category,next_at_target_tag>::value ||
- *          is_convertible<forward_category,next_in_facet_tag>::value;
- *       BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
- *       // Error message could be improved
- *       h = next_in_facet(hds,h);
- *       h = next_at_source(hds,h);
- *       h = next_at_target(hds,h);
- *       const_constraints(hds);
- *    }
- *    void const_constraints(HDS const& hds){
- *       h = next_in_facet(hds,h);
- *       h = next_at_source(hds,h);
- *       h = next_at_target(hds,h);
- *    }
- *    ForwardHDS hds;
- *    halfedge_descriptor h;
- *    halfedge_descriptor g;
- * };
- * \endcode
- */
+//forward_hds_concept.hpp  -*- C++ -*-
+//
+//@PURPOSE: Proviade 'ForwardHDS' concept definition and concept-checking class.
+//
+//@DESCRIPTION: This file provides a single class template that,
+// when used with the following concept-checking utilities:
+//..
+//  boost::function_requires<ForwardHDSConcept<HDS> >();
+//..
+// inside a function body, or
+//..
+//  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, ForwardHDSConcept);
+//..
+// inside a class body, checks whether the type given as template
+// argument is a model of the HDS concept described on the page
+// [forwardhds].
+//
+//@CONCEPT: [forwardhds] Forward HDS concept
+//
+///Definition
+///----------
+// This concept refines the 'HDSConcept', and specifies additional forward
+// category to iterate over the 'HDS' data structure, which means clockwise 
+// movement around the facet and counter clockwise movement around the
+// vertex. Possible forward categories are 'next_in_facet', 
+// 'next_at_source', and 'next_at_target'. Once one of these categories 
+// are given all others can be accessed with the help of the 'opposite' of a 
+// halfedge (see the section "Invariants" below for the algebraic relations
+// that must hold).
+//
+///Refinement of
+///-------------
+//  - 'HDSConcept'
+//
+///Notation
+///--------
+//  - 'HDS'    A type that is a model of 'ForwardHDSConcept'
+//  - 'hds'    A non-modifiable instance of 'HDS'
+//  - 'h','g'  Halfedge descriptors, of type 'hds_traits<HDS>::halfedge_descriptor'
+//
+///Associated types
+///----------------
+//  - 'hds_traits<HDS>::halfedge_descriptor': from 'HDSConcept'.
+//  - 'hds_traits<HDS>::traversal_category':  from 'HDSConcept', with
+//     additional requirement that this type must be convertible to
+//     'hdstl::forward_traversal_tag'.
+//  - 'hds_traits<HDS>::forward_category':    defines the pointer type for 
+//     forward iteration.
+//
+///Definitions
+///-----------
+//  - 'halfedge_descriptor' is a type that contains information to access 
+//     the halfedge.  (See the 'HDS' concept or a full definition.)
+//  - 'traversal_category' is a type that contains information about the 
+//     direction of the traversal, which is forward, forward or bidirectional.
+//     For this 'ForwardHDS' concept, the 'traversal_category' has to be convertible to  
+//     the 'hdstl::forward_traversal_tag' type defined in '<boost/hdstl.hpp>'.
+//  - 'forward_category' defines the primary accessor of the forward
+//     information for use by algorithms which desire the most direct access. 
+//
+///Valid Expressions
+///-----------------
+// In addition to the valid expressions of the 'HDS' concept:
+//   - 'next_in_facet(hds,h)' must return a value assignable to h.
+//   - 'next_at_source(hds,h)' must return a value assignable to h.
+//   - 'next_at_target(hds,h)' must return a value assignable to h.
+//
+///Expression Semantics
+///--------------------
+// In addition to the expression semantics of the 'HDS' concept:
+//   - 'next_in_facet(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' in the adjacent facet cycle, when facet cycles are
+//      oriented in counter-clockwise order.
+//   - 'next_at_source(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' around the source vertex of 'h', when halfedges are
+//      ordered around a given vertex in clockwise order.
+//   - 'next_at_target(hds,h)' returns a halfedge descriptor to the halfedge 
+//      preceding 'h' around the target vertex of 'h', when halfedges are
+//      ordered around a given vertex in clockwise order.
+//
+///Complexity guarantees
+///---------------------
+//  - 'next_in_facet(hds,h)': amortized constant time.
+//  - 'next_at_source(hds,h)': amortized constant time.
+//  - 'next_at_target(hds,h)': amortized constant time.
+//
+///Invariants 
+///----------
+// The forward halfedge accessors are linked via the algebraic relations:
+//   - 'next_in_facet(hds,h)'  == 'next_at_source(opposite(hds,h))' 
+//                             == 'opposite(next_at_target(hds,h))'
+//   - 'next_at_source(hds,h)' == 'next_in_facet(opposite(hds,h))'
+//                             == 'opposite(next_at_target(opposite(hds,h)))'
+//   - 'next_at_target(hds,h)' == 'opposite(next_in_facet(hds,h))' 
+//                             == 'opposite(next_at_source(opposite(hds,h)))'
+//
+///Concept-checking class
+///----------------------
+//..
+// template <class HDS> 
+// struct ForwardHDSConcept {
+//   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+//   typedef typename hds_traits<HDS>::traversal_category traversal_category;
+//   typedef typename hds_traits<HDS>::forward_category forward_category;
+//    void constraints() {
+//       using namespace boost;
+//       function_requires<HDSConcept<HDS> >();
+//       function_requires<ConvertibleConcept<traversal_category,
+//                                        hdstl::forward_traversal_tag> >();  
+//       const bool is_valid_storage_tag =
+//          is_convertible<forward_category,next_at_source_tag>::value ||
+//          is_convertible<forward_category,next_at_target_tag>::value ||
+//          is_convertible<forward_category,next_in_facet_tag>::value;
+//       BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
+//
+//       const_constraints(hds);
+//    }
+//    void const_constraints(HDS const& hds){
+//       h = next_in_facet(hds,h);
+//       h = next_at_source(hds,h);
+//       h = next_at_target(hds,h);
+//    }
+//    ForwardHDS hds;
+//    halfedge_descriptor h;
+//    halfedge_descriptor g;
+// };
+//..
 
 #ifdef BOOST_HDSTL_CONCEPTS_FORWARDHDSCONCEPT_HPP
 #define BOOST_HDSTL_CONCEPTS_FORWARDHDSCONCEPT_HPP 1
 
 namespace hdstl{
 namespace concepts{
-   /**
-    * @class ForwardHDSConcept
-    *
-    * @brief Forward HDS concept checking class.
-    * 
-    * @par Definition
-    * This class provides a concept checking class for the ForwardHDSConcept,
-    * i.e., using the statement boost::function_requires<ForwardHDSConcept<HDS>
-    * >() inside a function body, or BOOST_CLASS_REQUIRE(HDS, boost::hdstl,
-    * ForwardHDSConcept) inside a class definition body, should trigger a
-    * compile-time error if the type HDS does not model the ForwardHDSConcept.
-    */
-   template <class HDS> 
-   struct ForwardHDSConcept {
-      //@{
-      /** @name Required types: 
-       * The specialization of hds_traits<HDS> must have
-       * the required types below
-       */
-      typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
-      typedef typename hds_traits<HDS>::traversal_category traversal_category;
-      typedef typename hds_traits<HDS>::forward_category forward_category;
-      //@}
-
-      /**
-       * @name Defined constraints:
-       */
-      void constraints() {
-         using namespace boost;
-
-         function_requires<HDSConcept<HDS> >();
-         function_requires<ConvertibleConcept<traversal_category,
-                                                    forward_traversal_tag> >();  
-         const bool is_valid_storage_tag =
-            is_convertible<forward_category,next_at_source_tag>::value ||
-            is_convertible<forward_category,next_at_target_tag>::value ||
-            is_convertible<forward_category,next_in_facet_tag>::value;
-         BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
-         // Error message could be improved
-
-         h = next_in_facet(hds,h);
-         h = next_at_source(hds,h);
-         h = next_at_target(hds,h);
-         const_constraints(hds);
-      }
-      /**
-       * Defined const constraints
-       */
-      void const_constraints(HDS const& hds){
-         h = next_in_facet(hds,h);
-         h = next_at_source(hds,h);
-         h = next_at_target(hds,h);
-      }
-      
-      ForwardHDS hds;
-      halfedge_descriptor h;
-      halfedge_descriptor g;
-   };
+
+    template <class HDS> 
+    struct ForwardHDSConcept {
+        // This class provides a concept checking class for the ForwardHDSConcept,
+        // i.e., using the statement
+        //..
+        //  boost::function_requires<ForwardHDSConcept<HDS>()
+        //..
+        // inside a function body, or
+        //..
+        //  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, ForwardHDSConcept);
+        //..
+        // inside a class definition body, should trigger a compile-time error
+        // if the type HDS does not model the 'ForwardHDSConcept'.
+
+        // TYPES
+        typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+        typedef typename hds_traits<HDS>::traversal_category traversal_category;
+        typedef typename hds_traits<HDS>::forward_category forward_category;
+
+        // MANIPULATORS
+        void constraints() {
+            using namespace boost;
+
+            function_requires<HDSConcept<HDS> >();
+            function_requires<ConvertibleConcept<traversal_category,
+            forward_traversal_tag> >();  
+            const bool is_valid_storage_tag =
+                    is_convertible<forward_category,next_at_source_tag>::value ||
+                    is_convertible<forward_category,next_at_target_tag>::value ||
+                    is_convertible<forward_category,next_in_facet_tag>::value;
+            BOOST_STATIC_ASSERT( is_valid_storage_tag ); 
+
+            const_constraints(hds);
+        }
+
+        // ACCESSORS
+        void const_constraints(HDS const& hds){
+            h = next_in_facet(hds,h);
+            h = next_at_source(hds,h);
+            h = next_at_target(hds,h);
+        }
+
+      private:
+        // DATA
+        ForwardHDS hds;        // a halfedge data structure object
+        halfedge_descriptor h;  // a halfedge descriptor
+        halfedge_descriptor g;  // another halfedge descriptor
+    };
+
 }  // close namespace concepts
 }  // close namespace hdstl
 

Modified: sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/hds_concept.hpp
==============================================================================
--- sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/hds_concept.hpp	(original)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/hds_concepts/hds_concept.hpp	2007-06-12 01:55:14 EDT (Tue, 12 Jun 2007)
@@ -1,73 +1,99 @@
-/**
- * @file hds_concept.hpp
- *
- * @brief HDS concept definition.
- *
- * @par Definition
- * This concept is the basic HDS concept, which all the other HDS
- * concepts refine.  It contains a few requirements which are common to
- * all the graph concepts.  One should note that a model of HDS is not
- * required to be a model of Assignable, so algorithms should pass HDS
- * objects by reference.
- *
- * @par Refinement of:
- * This concept is not a refinement of another concept, in   particular a
- * model HDS of HDSConcept does @e not need to be DefaultConstructible,
- * CopyConstructible, or Assignable.
- *
- * @par Notation
- *  - HDS        A type that is a model of HDSConcept
- *  - hds        A non-modifiable instance of HDS
- *  - h,g        Halfedge descriptors, of type X::halfedge_descriptor
- *
- * @par Associated types
- *  - hds_traits<HDS>::halfedge_descriptor: must be DefaultConstructible and 
- *                         CopyConstructible, EqualityComparable, Assignable.
- *
- * @par Definitions
- * @e halfedge @e descriptor is a type that contains information to access
- * the halfedge.  Note that the halfedge descriptor type (accessible as a
- * member of the hds_traits<HDS> type) is an opaque type.  All that can be
- * done to it is passing it to the function opposite and letting the hds use
- * the information it contains to find the opposite halfedge.  In
- * particular, there is no guarantee that it is a pointer type.
- *
- * @par Valid Expressions
- *   - opposite(hds, h): Must return a value assignable to h.
- *
- * @par Expression Semantics
- *   - opposite(hds, h): Returns a descriptor to the halfedge opposite h in
- *     the data structure hds. Does not modify the state of either hds,
- *     or h.
- *
- * @par Complexity guarantees
- *   - opposite(hds, h): Amortized constant time.
- *
- * @par Invariants
- *   - Every valid halfedge descriptor h must have a valid opposite
- *     g = opposite(hds, h), @e distinct from h, such that
- *     opposite(hds, g) returns h.  (Hence, opposite is an involution.)
- *
- * @par Concept-checking class
- * \code
- * template <class HDS> 
- * struct HDSConcept {
- *   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
- *   void constraints() {
- *     using namespace boost;
- *     function_requires<DefaultConstructibleConcept<halfedge_descriptor> >();
- *     function_requires<CopyConstructibleConcept<halfedge_descriptor> >();
- *     function_requires<EqualityComparableConcept<halfedge_descriptor> >();
- *     function_requires<AssignableConcept<halfedge_descriptor> >();
- *     h = opposite(hds,h);
- *     const_constraints(hds);
- *   }
- *   void const_constraints(HDS const& hds) {
- *     h = opposite(hds,h);
- *   }
- * };
- * \endcode
- */
+//hds_concept.hpp   -*- C++ -*-
+//
+//@PURPOSE: Provide 'HDS' concept definition and concept-checking class.
+//
+//@DESCRIPTION: This file provides a single class template that,
+// when used with the following concept-checking utilities:
+//..
+//  boost::function_requires<HDSConcept<HDS> >();
+//..
+// inside a function body, or
+//..
+//  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, HDSConcept);
+//..
+// inside a class body, checks whether the type given as template
+// argument is a model of the HDS concept described on the page
+// [hdsconcept].
+//
+//@CONCEPT: [hdsconcept] HDS concept definition
+//
+///Definition
+///----------
+// This concept is the basic 'HDSConcept', which all the other 'HDS'
+// concepts refine.  It contains a few requirements which are common to
+// all the graph concepts.  One should note that a model of 'HDSConcept' is not
+// required to be a model of 'Assignable', so algorithms should pass 'HDS'
+// objects by reference.
+//
+///Refinement of:
+///--------------
+// This concept is not a refinement of another concept, in   particular a
+// model 'HDS' of 'HDSConcept' does *not* need to be 'DefaultConstructible',
+// 'CopyConstructible', or 'Assignable'.
+//
+///Notation
+///--------
+//  - 'HDS'    A type that is a model of 'HDSConcept'
+//  - 'hds'    A non-modifiable instance of 'HDS'
+//  - 'h','g'  Halfedge descriptors, of type 'hds_traits<HDS>::halfedge_descriptor'
+//
+///Associated types
+///----------------
+//  - 'hds_traits<HDS>::halfedge_descriptor': must be 'DefaultConstructible' and 
+//    'CopyConstructible', 'EqualityComparable', 'Assignable'.
+//
+///Definitions
+///-----------
+// 'halfedge_descriptor' is a type that contains information to access
+// the halfedge.  Note that the halfedge descriptor type (accessible as a
+// member of the 'hds_traits<HDS>' type) is an opaque type.  All that can be
+// done to it is passing it to the function opposite and letting the hds use
+// the information it contains to find the opposite halfedge.  In
+// particular, there is no guarantee that it is a pointer type.
+//
+///Valid Expressions
+///-----------------
+// The following expression must be valid and obey the syntactic requirement:
+//   - 'opposite(hds, h)' must return a value assignable to 'h'.
+//
+///Expression Semantics
+///--------------------
+// The expressions semantics are as follows:
+//   - 'opposite(hds, h)' returns a descriptor to the halfedge opposite 'h' in
+//     the data structure 'hds'. Does not modify the state of either 'hds'
+//     or 'h'.
+//
+///Complexity guarantees
+///---------------------
+//   - 'opposite(hds, h)': Amortized constant time.
+//
+///Invariants
+///----------
+// Every valid halfedge descriptor 'h' must have a valid opposite
+// 'g = opposite(hds, h)', *distinct* from h, such that
+// 'opposite(hds, g)' returns 'h'.  (Hence, 'opposite' is an involution.)
+//
+///Concept-checking class
+///----------------------
+//..
+// template <class HDS> 
+// struct HDSConcept {
+//   typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+//   void constraints() {
+//     using namespace boost;
+//     function_requires<DefaultConstructibleConcept<halfedge_descriptor> >();
+//     function_requires<CopyConstructibleConcept<halfedge_descriptor> >();
+//     function_requires<EqualityComparableConcept<halfedge_descriptor> >();
+//     function_requires<AssignableConcept<halfedge_descriptor> >();
+//     h = opposite(hds,h);
+//     const_constraints(hds);
+//   }
+//   void const_constraints(HDS const& hds) {
+//     h = opposite(hds,h);
+//   }
+//..
+
+#include <boost/concepts.h>
 
 #ifdef BOOST_HDSTL_CONCEPTS_HDSCONCEPT_HPP
 #define BOOST_HDSTL_CONCEPTS_HDSCONCEPT_HPP 1
@@ -75,52 +101,53 @@
 namespace hdstl{
 namespace concepts {
 
-   /**
-    * @class HDSConcept
-    *
-    * @brief HDS concept checking class
-    *
-    * @par Definition
-    * This class provides a concept checking class for the HDSConcept, i.e.,
-    * using the statement boost::function_requires<HDSConcept<HDS> >() inside a
-    * function body, or BOOST_CLASS_REQUIRE(HDS, boost::hdstl, HDSConcept)
-    * inside a class definition body, should trigger a compile-time error if
-    * the type HDS does not model the HDSConcept.
-    */
-   template <class HDS> 
-   struct HDSConcept {
-      //@{
-      /** @name Required types: 
-       * The specialization of hds_traits<HDS> must have the required types
-       * below, obeying the types requirements stated in the detailed
-       * description.
-       */
-      typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
-      //@}
-
-      /**
-       * @name Defined constraints:
-       */
-      void constraints() {
-         using namespace boost;
-         function_requires<DefaultConstructibleConcept<halfedge_descriptor> >();
-         function_requires<CopyConstructibleConcept<halfedge_descriptor> >();
-         function_requires<EqualityComparableConcept<halfedge_descriptor> >();
-         function_requires<AssignableConcept<halfedge_descriptor> >();
-
-         h = opposite(hds,h);
-         const_constraints(hds);
-      }
-
-      /**
-       * Defined const constraints:
-       */
-      void const_constraints(HDS const& hds) {
-         h = opposite(hds,h);
-      }
-      HDS hds;
-      halfedge_descriptor h;
-   };
+    template <class HDS> 
+    struct HDSConcept {
+        // This class provides a concept checking class for the
+        // 'HDS' concept defined in [hdsconcept], i.e., using the statement
+        //..
+        //  boost::function_requires<HDSConcept<HDS> >();
+        //..
+        // inside a function body, or
+        //..
+        //  BOOST_CLASS_REQUIRE(HDS, boost::hdstl, HDSConcept);
+        //..
+        // inside a class definition body, should trigger a compile-time
+        // error if the type 'HDS' does not model the 'HDS' concept.
+
+        // TYPES
+        typedef typename hds_traits<HDS>::halfedge_descriptor halfedge_descriptor; 
+            // The specialization of 'hds_traits<HDS>' must have these required
+            // types, obeying the types requirements stated in the detailed
+            // description of the 'HDS' concept on page [hdsconcept].
+
+        // MANIPULATORS
+        void constraints()
+            // Check that the 'HDS' template parameters satisfies all the
+            // constraints of 'HDSConcept' on page [hdsconcept].
+        {
+            using namespace boost;
+            function_requires<DefaultConstructibleConcept<halfedge_descriptor> >();
+            function_requires<CopyConstructibleConcept<halfedge_descriptor> >();
+            function_requires<EqualityComparableConcept<halfedge_descriptor> >();
+            function_requires<AssignableConcept<halfedge_descriptor> >();
+           
+            const_constraints(hds);
+        }
+
+        // ACCESSORS
+        void const_constraints(HDS const& hds)
+            // Check that the non-modifiable 'HDS' template parameters
+            // satisfies all the constraints of 'HDSConcept'.
+        {
+            h = opposite(hds,h);
+        }
+
+      private:
+	// DATA
+        HDS hds;                 // a halfedge data structure object
+        halfedge_descriptor h;   // a halfedge descriptor
+    };
 
 }  // close namespace concepts
 }  // close namespace hdstl