[Olena-patches] 993: Add some documentation.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Thierry Geraud &lt;thierry.geraud(a)lrde.epita.fr&gt; Add some documentation. * doc/Doxyfile.in: Try to properly handle some macros. * mln/core/macros.hh, * mln/core/concept/genpoint.hh, * mln/core/concept/point_set.hh, * mln/core/concept/psite.hh, * mln/core/concept/object.hh, * mln/core/concept/window.hh, * mln/core/concept/box.hh, * mln/core/concept/point.hh, * mlc/equal.hh, * mlc/same_point.hh, * mln/core/concept/iterator.hh: Add some documentation. * mln/core/concept/doc/image.hh: New. * mln/core/concept/doc/genpoint.hh: Update. * mln/core/concept/doc/piter.hh: New. * mln/core/concept/doc/point_set.hh: New. * mln/core/concept/doc/object.hh: New. * mln/core/concept/doc/neighborhood.hh: New. * mln/core/concept/doc/window.hh: New. * mln/core/concept/doc/box.hh: New. * mln/core/concept/doc/iterator.hh: New. * mln/core/concept/doc/dpoint.hh: New. * mln/core/contract.hh: New. * mlc/same_coord.hh: New. doc/Doxyfile.in | 10 +- mlc/equal.hh | 6 - mlc/same_coord.hh | 24 ++++++ mlc/same_point.hh | 10 +- mln/core/concept/box.hh | 17 +++- mln/core/concept/doc/box.hh | 54 ++++++++++++++ mln/core/concept/doc/dpoint.hh | 25 ++++++ mln/core/concept/doc/genpoint.hh | 44 ++++++++++- mln/core/concept/doc/image.hh | 54 ++++++++++++++ mln/core/concept/doc/iterator.hh | 42 +++++++++++ mln/core/concept/doc/neighborhood.hh | 24 ++++++ mln/core/concept/doc/object.hh | 30 ++++++++ mln/core/concept/doc/piter.hh | 29 +++++++ mln/core/concept/doc/point_set.hh | 55 ++++++++++++++ mln/core/concept/doc/window.hh | 51 +++++++++++++ mln/core/concept/genpoint.hh | 130 +++++++++++++++++++++++++++++++---- mln/core/concept/iterator.hh | 22 +++++ mln/core/concept/object.hh | 2 mln/core/concept/point.hh | 41 +++++++++-- mln/core/concept/point_set.hh | 9 ++ mln/core/concept/psite.hh | 6 - mln/core/concept/window.hh | 9 ++ mln/core/contract.hh | 20 +++++ mln/core/macros.hh | 9 ++ 24 files changed, 681 insertions(+), 42 deletions(-) Index: doc/Doxyfile.in --- doc/Doxyfile.in (revision 992) +++ doc/Doxyfile.in (working copy) @@ -1007,13 +1007,13 @@ # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. @@ -1049,7 +1049,11 @@ # sources will be used. Use the PREDEFINED tag if you want to use a # different macro definition. -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = \ + mln_point \ + mln_dpoint \ + mln_coord + # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then # doxygen's preprocessor will remove all function-like macros that are alone Index: mln/core/macros.hh --- mln/core/macros.hh (revision 992) +++ mln/core/macros.hh (working copy) @@ -5,11 +5,20 @@ * This file defines the set of milena macros. */ +/*! \def mln_point(T) + */ # define mln_point(T) typename T::point + +/*! \def mln_dpoint(T) + */ # define mln_dpoint(T) typename T::dpoint + # define mln_psite(T) typename T::psite # define mln_pset(T) typename T::pset # define mln_box(T) typename T::box + +/*! \def mln_coord(T) + */ # define mln_coord(T) typename T::coord # define mln_piter(T) typename T::piter Index: mln/core/concept/genpoint.hh --- mln/core/concept/genpoint.hh (revision 992) +++ mln/core/concept/genpoint.hh (working copy) @@ -2,33 +2,40 @@ # define MLN_CORE_CONCEPT_GENPOINT_HH /*! \file mln/core/concept/genpoint.hh - * This file defines the concept of mln::GenPoint. + * \brief This file defines the concept of mln::GenPoint. */ +# include <mlc/equal.hh> +# include <mlc/same_point.hh> +# include <mlc/same_coord.hh> # include <mln/core/concept/object.hh> # include <mln/core/macros.hh> -# include <mlc/equal.hh> -# include <mlc/same_point.hh> +# include <mln/core/contract.hh> namespace mln { - /*! Base class for implementation classes that are points or that + // FIXME: \class GenPoint genpoint.hh "mln/core/concept/doc/genpoint.hh" + + /*! \brief Base class for implementation classes that are points or that * have the behavior of points. * - * "GenPoint" is "General Point" for short. + * "GenPoint" is "Generalized Point" for short. * - * This class does not derive from mln::Object; it is for use as a - * parallel hierarchy. + * \warning This class does \em not derive from mln::Object; it is + * for use as a parallel hierarchy. * - * \relates mln::doc::GenPoint + * \see mln::doc::GenPoint for a complete documentation of this + * class contents. */ template <typename E> struct GenPoint // stand-alone class! { /* + enum { dim }; + typedef point; typedef dpoint; typedef coord; @@ -47,22 +54,112 @@ - /*! \relates mln::GenPoint + /*! \brief Equality comparison between a couple of generalized point \p lhs + * and \p rhs. + * + * @param[in] lhs A first generalized point. + * @param[in] rhs A second generalized point. + * + * \pre Both \p lhs and \p rhs have to be defined on the same + * topology; otherwise this test does not compile. + * + * \return True if both generalized points have the same + * coordinates, otherwise false. + * + * \relates mln::GenPoint */ template <typename Pl, typename Pr> bool operator=(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); + + /*! \brief Ordering "less than" comparison between a couple of generalized + * point \p lhs and \p rhs. + * + * @param[in] lhs A first generalized point. + * @param[in] rhs A second generalized point. + * + * This test is based on a lexicographical ordering over coordinates. + * + * \warning In the general case this ordering relationship is \em + * not bound to the way of browsing a domain with a forward point + * iterator. + * + * \pre Both \p lhs and \p rhs have to be defined on the same + * topology; otherwise this test does not compile. + * + * \return True if \p lhs is before \p rhs in the sense of the + * coordinates lexicographic comparison, otherwise false. + * + * \relates mln::GenPoint + */ template <typename Pl, typename Pr> bool operator<(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); + + /*! \brief Difference between a couple of generalized point \p lhs and \p + * rhs. + * + * @param[in] lhs A first generalized point. + * @param[in] rhs A second generalized point. + * + * \warning There is no type promotion in milena so the client + * has to make sure that both points are defined with the same + * type of coordinates. + * + * \pre Both \p lhs and \p rhs have to be defined on the same + * topology and with the same type of coordinates; otherwise this + * test does not compile. + * + * \post The result, \p dp, is such as \p lhs = \p rhs + \p dp. + * + * \return A delta-point. + * + * \see mln::Dpoint + * \relates mln::GenPoint + */ template <typename Pl, typename Pr> - typename Pl::dpoint + mln_dpoint(Pl) operator-(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); + + /*! \brief Add a delta-point \p rhs to a generalized point \p lhs. + * + * @param[in] lhs A generalized point. + * @param[in] rhs A delta-point. + * + * The type of \p rhs has to be exactly the delta-point type + * associated with the type of \p lhs. + * + * \return A new point (temporary object). + * + * \see mln::Dpoint + * \relates mln::GenPoint + * + * \todo Introduce the notion of "generalized dpoint" and + * add the more general extra operator+(GenPoint, GenDpoint). + */ template <typename P> - typename P::point - operator+(const GenPoint<P>& lhs, const typename P::dpoint& rhs); + mln_point(P) + operator+(const GenPoint<P>& lhs, const mln_dpoint(P)& rhs); + + /*! \brief Print a generalized point \p p into the output stream \p + * ostr. + * + * @param[in,out] ostr An output stream. + * @param[in] p A generalized point. + * + * The type of \p rhs has to be exactly the delta-point type + * associated with the type of \p lhs. + * + * \return The modified output stream. + * + * \see mln::Dpoint + * \relates mln::GenPoint + * + * \todo Introduce the notion of "generalized dpoint" and + * add the more general extra operator+(GenPoint, GenDpoint). + */ template <typename P> std::ostream& operator<<(std::ostream& ostr, const GenPoint<P>& p); @@ -72,6 +169,8 @@ template <typename E> GenPoint<E>::GenPoint() { + const int dim = E::dim; + invariant(dim > 0); typedef mln_point(E) point; typedef mln_dpoint(E) dpoint; typedef mln_coord(E) coord; @@ -84,6 +183,7 @@ template <typename Pl, typename Pr> bool operator=(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs) { + // FIXME: mlc::same_grid<Pl, Pr>::check(); const Pl& lhs_ = force_exact<Pl>(lhs); const Pr& rhs_ = force_exact<Pr>(rhs); mlc::same_point<Pl, Pr>::check(); @@ -96,7 +196,7 @@ template <typename Pl, typename Pr> bool operator<(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs) { - mlc::same_point<Pl, Pr>::check(); + // FIXME: mlc::same_grid<Pl, Pr>::check(); const Pl& lhs_ = force_exact<Pl>(lhs); const Pr& rhs_ = force_exact<Pr>(rhs); for (unsigned i = 0; i < Pl::dim; ++i) @@ -113,11 +213,15 @@ mln_dpoint(Pl) operator-(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs) { + mlc::equal<mln_dpoint(Pl), mln_dpoint(Pr)>::check(); + // FIXME: mlc::same_grid<Pl, Pr>::check(); + mlc::same_coord<Pl, Pr>::check(); const Pl& lhs_ = force_exact<Pl>(lhs); const Pr& rhs_ = force_exact<Pr>(rhs); mln_dpoint(Pl) tmp; for (unsigned i = 0; i < Pl::dim; ++i) tmp[i] = lhs_[i] - rhs_[i]; + assert(rhs + tmp = lhs); return tmp; } Index: mln/core/concept/point_set.hh --- mln/core/concept/point_set.hh (revision 992) +++ mln/core/concept/point_set.hh (working copy) @@ -1,6 +1,10 @@ #ifndef MLN_CORE_CONCEPT_POINT_SET_HH # define MLN_CORE_CONCEPT_POINT_SET_HH +/*! \file mln/core/concept/point_set.hh + * \brief This file defines the concept of mln::Point_Set. + */ + # include <mln/core/concept/point.hh> # include <mln/core/concept/piter.hh> @@ -8,6 +12,11 @@ namespace mln { + /*! \brief Base class for implementation classes of point sets. + * + * \see mln::doc::Point_Set for a complete documentation of this + * class contents. + */ template <typename E> struct Point_Set : public Object<E> { Index: mln/core/concept/psite.hh --- mln/core/concept/psite.hh (revision 992) +++ mln/core/concept/psite.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_PSITE_HH /*! \file mln/core/concept/psite.hh - * This file defines the concept of mln::Psite. + * \brief This file defines the concept of mln::Psite. */ # include <mln/core/concept/genpoint.hh> @@ -11,8 +11,8 @@ namespace mln { - /*! Base class for implementation classes of the notion of "point - * site". + /*! \brief Base class for implementation classes of the notion of + * "point site". * * A point site ("psite" for short) is an object that allows an * efficient access to data associated with a point. A point site Index: mln/core/concept/object.hh --- mln/core/concept/object.hh (revision 992) +++ mln/core/concept/object.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_OBJECT_HH /*! \file mln/core/concept/object.hh - * This file contains the top milena class. + * \brief This file contains the top milena class. */ # include <cassert> Index: mln/core/concept/doc/image.hh --- mln/core/concept/doc/image.hh (revision 0) +++ mln/core/concept/doc/image.hh (revision 0) @@ -0,0 +1,54 @@ +/*! \file mln/core/concept/doc/image.hh + * This file documents the concept of mln::Image. + */ + +namespace mln +{ + + namespace doc + { + + /*! Documentation class for mln::Image. + * \see mln::Image + */ + template <typename E> + struct Image : public Object<E> + { + // to be provided in concrete image classes: + + typedef void value; + typedef void rvalue; + typedef void lvalue; + + bool has_data() const; + + bool owns_(const psite& p) const; // default is like "has(p)" + const pset& domain() const; + + rvalue operator()(const psite& p) const; + lvalue operator()(const psite& p); + + template <typename T> + struct change_value + { + typedef ret; + }; + + + // provided by internal::image_base_: + + typedef void pset; + typedef void point; + typedef void psite; + + typedef void piter; + typedef void fwd_piter; + typedef void bkd_piter; + + bool has(const psite& p) const; + const box_<point>& bbox() const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/genpoint.hh --- mln/core/concept/doc/genpoint.hh (revision 992) +++ mln/core/concept/doc/genpoint.hh (working copy) @@ -1,5 +1,5 @@ -/*! \file mln/core/concept/genpoint.doc.hh - * This file documents the concept of mln::GenPoint. +/*! \file mln/core/concept/doc/genpoint.hh + * \brief This file documents the concept of mln::GenPoint. */ namespace mln @@ -8,18 +8,54 @@ namespace doc { + /*! \brief Documentation class for mln::GenPoint. + * \see mln::GenPoint + */ template <typename E> struct GenPoint { - typedef void point; ///< Associated type of point. + /*! \var dim + * \brief Dimension of the space. + * \invariant dim > 0 + */ + enum { dim }; + + /*! \brief Point associated type. + * \invariant This type has to derive from mln::Point. + */ + typedef void point; + /*! \brief Dpoint associated type. + * \invariant This type has to derive from mln::Dpoint. + */ typedef void dpoint; + + /*! Coordinate associated type. + */ typedef void coord; + + + // FIXME: // typedef void topo; + // operator point() const; - operator point() const; + /*! \brief Give a hook to the point address. + * + * This method allows for iterators to refer to a point. + * + * \return A point address. + */ const point* pointer() const; + + /*! \brief Read-only access to the \p i-th coordinate value. + * + * @param[in] i The coordinate index. + * + * \pre \p i < \c dim + * + * \return The value of the \p i-th coordinate. + */ coord operator[](unsigned i) const; }; Index: mln/core/concept/doc/piter.hh --- mln/core/concept/doc/piter.hh (revision 0) +++ mln/core/concept/doc/piter.hh (revision 0) @@ -0,0 +1,29 @@ +/*! \file mln/core/concept/doc/piter.hh + * \brief This file documents the concept of mln::Piter. + */ + +namespace mln +{ + + namespace doc + { + + /*! \brief Documentation class for mln::Piter. + * \see mln::Piter + */ + template <typename E> + struct Piter : public Iterator<E>, + public GenPoint<E> + { + // FIXME: HERE + typedef void psite; + typedef void point; + + operator psite() const; + operator point() const; + const point* pointer() const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/point_set.hh --- mln/core/concept/doc/point_set.hh (revision 0) +++ mln/core/concept/doc/point_set.hh (revision 0) @@ -0,0 +1,55 @@ +/*! \file mln/core/concept/doc/point_set.hh + * \brief This file documents the concept of mln::Point_Set. + */ + +namespace mln +{ + + namespace doc + { + + /*! \brief Documentation class for mln::Point_Set. + * \see mln::Point_Set + */ + template <typename E> + struct Point_Set : public Object<E> + { + /*! \brief Point associated type. + */ + typedef void point; + + /*! \brief Psite associated type. + */ + typedef void psite; + + /*! \brief Piter associated type. + */ + typedef void piter; + + /*! \brief Forward Piter associated type. + */ + typedef void fwd_piter; + + /*! \brief Backward Piter associated type. + */ + typedef void bkd_piter; + + /*! \brief Test if the \p p belongs to this point set. + * + * @param[in] p A point site. + * \return True if \p p is an element of the point set. + */ + bool has(const psite& p) const; + + /*! \brief Give the bounding box of this point set. + */ + const box_<point>& bbox() const; + + /*! \brief Give the number of points of this point set. + */ + std::size_t npoints() const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/object.hh --- mln/core/concept/doc/object.hh (revision 0) +++ mln/core/concept/doc/object.hh (revision 0) @@ -0,0 +1,30 @@ +/*! \file mln/core/concept/doc/object.hh + * \brief This file documents the concept of mln::Object. + */ + +namespace mln +{ + /*! \namespace mln::doc + * \brief The namespace mln::doc is only for documentation purpose. + * + * Since concepts are not yet part of the C++ Standard, they are not + * explicitly expressed in code. Their documentation is handled by + * their respective ghost class, located in this namespace. + * + * \warning The ghost classes located in mln::doc should not be used + * by the client. + */ + namespace doc + { + + /*! \brief Documentation class for mln::Object. + * \see mln::Object + */ + template <typename E> + struct Object + { + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/neighborhood.hh --- mln/core/concept/doc/neighborhood.hh (revision 0) +++ mln/core/concept/doc/neighborhood.hh (revision 0) @@ -0,0 +1,24 @@ +/*! \file mln/core/concept/doc/neighborhood.hh + * This file documents the concept of mln::Neighborhood. + */ + +namespace mln +{ + + namespace doc + { + + /*! Documentation class for mln::Neighborhood. + * \see mln::Neighborhood + */ + template <typename E> + struct Neighborhood : public Object<E> + { + typedef void niter; + typedef void fwd_niter; + typedef void bkd_niter; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/window.hh --- mln/core/concept/doc/window.hh (revision 0) +++ mln/core/concept/doc/window.hh (revision 0) @@ -0,0 +1,51 @@ +/*! \file mln/core/concept/doc/window.hh + * \brief This file documents the concept of mln::Window. + */ + +namespace mln +{ + + namespace doc + { + + /*! \brief Documentation class for mln::Window. + * \see mln::Window + */ + template <typename E> + struct Window : public Object<E> + { + /*! \brief Piter type associated to this window to browse its + * points. + */ + typedef void qiter; + + /*! \brief Piter type associated to this window to browse its + * points in a forward way. + */ + typedef void fwd_qiter; + + /*! \brief Piter type associated to this window to browse its + * points in a backward way. + */ + typedef void bkd_qiter; + + /*! \brief Test if the window is empty. + * + * A window of null size is empty. + */ + bool is_empty() const; + + /*! \brief Test if the window is centered. + * + * A window is centered is the origin belongs to the window. + */ + bool is_centered() const; + + /*! \brief Test if the window is symmetric. + */ + bool is_symmetric() const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/box.hh --- mln/core/concept/doc/box.hh (revision 0) +++ mln/core/concept/doc/box.hh (revision 0) @@ -0,0 +1,54 @@ +/*! \file mln/core/concept/doc/box.hh + * This file documents the concept of mln::Box. + */ + +namespace mln +{ + + namespace doc + { + + /*! Documentation class for mln::Box. + * \see mln::Box + */ + template <typename E> + struct Box : public Point_Set<E> + { + /*! \fn const point& pmin() const + * + * Return the minimum point w.r.t. the ordering between points. + * + * In 2D this minimum is the top left point of the box. + */ + const point& pmin() const; + + /*! \fn const point& pmax() const + * + * Return the maximum point w.r.t. the ordering between points. + * + * In 2D this maximum is the bottom right point of the box. + */ + const point& pmax() const; + + /*! \fn const E& bbox() const + * + * Return the bounding box of this point set, so that is itself. + * This method is declared by the mln::Point_Set concept. + * + * \warning This method is final for all box classes. + */ + const E& bbox() const; + + /*! \fn std::size_t npoints() const + * + * Return the number of points of this box. This method is + * declared by the mln::Point_Set concept. + * + * \warning This method is final for all box classes. + */ + std::size_t npoints() const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/iterator.hh --- mln/core/concept/doc/iterator.hh (revision 0) +++ mln/core/concept/doc/iterator.hh (revision 0) @@ -0,0 +1,42 @@ +/*! \file mln/core/concept/doc/iterator.hh + * This file documents the concept of mln::Iterator. + */ + + +namespace mln +{ + + namespace doc + { + + /*! Documentation class for mln::Iterator. + * \see mln::Iterator + */ + template <typename E> + struct Iterator : public Object<E> + { + /*! Returns true if the iterator is valid, that is, designates + * an element. + */ + bool is_valid() const; + + /*! Invalidate the iterator. + */ + void invalidate(); + + /*! Start an iteration, that is, make the iterator designate the + * first element if it exists. + */ + void start(); + + /*! Make the iterator designate the next element. + */ + void next_(); + + protected: + Iterator(); + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/doc/dpoint.hh --- mln/core/concept/doc/dpoint.hh (revision 0) +++ mln/core/concept/doc/dpoint.hh (revision 0) @@ -0,0 +1,25 @@ +/*! \file mln/core/concept/doc/dpoint.hh + * This file documents the concept of mln::Dpoint. + */ + +namespace mln +{ + + namespace doc + { + + /*! Documentation class for mln::Dpoint. + * \see mln::Dpoint + */ + template <typename E> + struct Dpoint : public Object<E> + { + typedef point; + typedef coord; + enum { dim }; + coord operator[](unsigned i) const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: mln/core/concept/window.hh --- mln/core/concept/window.hh (revision 992) +++ mln/core/concept/window.hh (working copy) @@ -1,12 +1,21 @@ #ifndef MLN_CORE_CONCEPT_WINDOW_HH # define MLN_CORE_CONCEPT_WINDOW_HH +/*! \file mln/core/concept/window.hh + * \brief This file defines the concept of mln::Window. + */ + # include <mln/core/concept/object.hh> namespace mln { + /*! \brief Base class for implementation classes that are windows. + * + * \see mln::doc::Window for a complete documentation of this class + * contents. + */ template <typename E> struct Window : public Object<E> { Index: mln/core/concept/box.hh --- mln/core/concept/box.hh (revision 992) +++ mln/core/concept/box.hh (working copy) @@ -1,12 +1,24 @@ #ifndef MLN_CORE_CONCEPT_BOX_HH # define MLN_CORE_CONCEPT_BOX_HH +/*! \file mln/core/concept/box.hh + * \brief This file defines the concept of mln::Box. + */ + # include <mln/core/concept/point_set.hh> namespace mln { + /*! \brief Base class for implementation classes of boxes. + * + * Boxes are particular point sets useful to bound any set of + * points. + * + * \see mln::doc::Box for a complete documentation of this class + * contents. + */ template <typename E> struct Box : public Point_Set<E> { @@ -15,9 +27,8 @@ const point& pmax() const; */ - // final - const E& bbox() const; - std::size_t npoints() const; + const E& bbox() const; //! final; \see mln::doc::Box::bbox + std::size_t npoints() const; //! final; \see mln::doc::Box::npoints protected: Box(); Index: mln/core/concept/point.hh --- mln/core/concept/point.hh (revision 992) +++ mln/core/concept/point.hh (working copy) @@ -1,8 +1,8 @@ #ifndef MLN_CORE_CONCEPT_POINT_HH # define MLN_CORE_CONCEPT_POINT_HH -/*! \file mln/core/exact.hh - * This file defines the concept of mln::Point. +/*! \file mln/core/concept/point.hh + * \brief This file defines the concept of mln::Point. */ # include <mln/core/concept/psite.hh> @@ -11,15 +11,19 @@ namespace mln { - /*! Base class for implementation of point. + /*! \brief Base class for implementation of point classes. * - * A point is + * A point is a vector in a space. */ template <typename P> struct Point : public Psite<P> { - // final + /*! \brief The associated point type is itself. + */ typedef P point; + + /*! \brief The pointer is this point address. + */ const P* pointer() const; protected: @@ -27,9 +31,36 @@ }; + /*! \brief Add a delta-point \p rhs to a point \p lhs. + * + * @param[in,out] lhs The targeted point. + * @param[in] rhs A delta-point. + * + * \pre The type of \p rhs has to be the Dpoint type associated with + * the type of \p lhs; otherwise this test does not compile. + * + * \return A reference to the point \p lhs once translated by \p + * rhs. + * + * \relates mln::Point + */ template <typename P> P& operator+=(Point<P>& lhs, const mln_dpoint(P)& rhs); + + /*! \brief Remove a delta-point \p rhs to a point \p lhs. + * + * @param[in,out] lhs The targeted point. + * @param[in] rhs A delta-point. + * + * \pre The type of \p rhs has to be the Dpoint type associated with + * the type of \p lhs; otherwise this test does not compile. + * + * \return A reference to the point \p lhs once translated by - \p + * rhs. + * + * \relates mln::Point + */ template <typename P> P& operator-=(Point<P>& lhs, const mln_dpoint(P)& rhs); Index: mln/core/concept/iterator.hh --- mln/core/concept/iterator.hh (revision 992) +++ mln/core/concept/iterator.hh (working copy) @@ -1,15 +1,25 @@ #ifndef MLN_CORE_CONCEPT_ITERATOR_HH # define MLN_CORE_CONCEPT_ITERATOR_HH -# include <mln/core/concept/object.hh> +/*! \file mln/core/concept/iterator.hh + * \brief This file defines the concept of mln::Iterator. + */ +# include <mln/core/concept/object.hh> +/*! \brief Loop to browse all the elements targetted by the iterator + * \p x. + */ # define for_all(x) for(x.start(); x.is_valid(); x.next()) namespace mln { - + /*! \brief Base class for implementation classes that are iterators. + * + * \see mln::doc::Iterator for a complete documentation of this + * class contents. + */ template <typename E> struct Iterator : public Object<E> { @@ -20,6 +30,14 @@ void next_(); */ + /*! \brief Go to the next element. + * + * \warning This is a final method; iterator classes should not + * re-defined this method. The actual "next" operation has to be + * defined through the \em next_ method. + * + * \pre The iterator is valid. + */ void next(); // final protected: Index: mln/core/contract.hh --- mln/core/contract.hh (revision 0) +++ mln/core/contract.hh (revision 0) @@ -0,0 +1,20 @@ +#ifndef MLN_CORE_CONTRACT_HH +# define MLN_CORE_CONTRACT_HH + +/*! \file mln/core/contract.hh + * This file defines the set of contracts. + */ + +# include <cassert> + + +# define mln_assertion(expr) assert(expr) + +# define mln_invariant(expr) assert(expr) +# define mln_precondition(expr) assert(expr) +# define mln_postcondition(expr) assert(expr) + +# define mln_implies(lexpr, repxr) assert(not (rexpr) or (lexpr)) + + +#endif // ! MLN_CORE_CONTRACT_HH Index: mlc/equal.hh --- mlc/equal.hh (revision 992) +++ mlc/equal.hh (working copy) @@ -1,5 +1,5 @@ -#ifndef MLN_MLC_EQUAL_HH -# define MLN_MLC_EQUAL_HH +#ifndef MLC_EQUAL_HH +# define MLC_EQUAL_HH namespace mln @@ -25,4 +25,4 @@ } // end of namespace mln -#endif // ! MLN_MLC_EQUAL_HH +#endif // ! MLC_EQUAL_HH Index: mlc/same_coord.hh --- mlc/same_coord.hh (revision 0) +++ mlc/same_coord.hh (revision 0) @@ -0,0 +1,24 @@ +#ifndef MLC_SAME_COORD_HH +# define MLC_SAME_COORD_HH + +# include <mlc/equal.hh> +# include <mln/core/macros.hh> + + +namespace mln +{ + + namespace mlc + { + + template <typename T1, typename T2> + struct same_coord : mlc::equal<mln_coord(T1), mln_coord(T2)> + { + }; + + } // end of namespace mln::mlc + +} // end of namespace mln + + +#endif // ! MLC_SAME_COORD_HH Index: mlc/same_point.hh --- mlc/same_point.hh (revision 992) +++ mlc/same_point.hh (working copy) @@ -1,8 +1,8 @@ -#ifndef MLN_MLC_SAME_POINT_HH -# define MLN_MLC_SAME_POINT_HH +#ifndef MLC_SAME_POINT_HH +# define MLC_SAME_POINT_HH # include <mlc/equal.hh> -# include <core/macros.hh> +# include <mln/core/macros.hh> namespace mln @@ -12,7 +12,7 @@ { template <typename T1, typename T2> - struct same_point : mlc::equal<mln_point(T2), mln_point(T2)> + struct same_point : mlc::equal<mln_point(T1), mln_point(T2)> { }; @@ -21,4 +21,4 @@ } // end of namespace mln -#endif // ! MLN_MLC_SAME_POINT_HH +#endif // ! MLC_SAME_POINT_HH