Boost logo

Boost-Commit :

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


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk