[Olena-patches] 991: Start milena documentation.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Thierry Geraud &lt;thierry.geraud(a)lrde.epita.fr&gt; Start milena documentation. * core/macros.hh, * core/concept/genpoint.hh, * core/concept/psite.hh, * core/concept/object.hh, * core/concept/point.hh, * core/ops.hh, * core/exact.hh: Add some documentation. * core/concept/doc: New. * core/concept/doc/genpoint.hh: New. * mlc/equal.hh: Remove include. core/concept/doc/genpoint.hh | 28 ++++++++++++++++++++++++++++ core/concept/genpoint.hh | 24 +++++++++++++++++++++--- core/concept/object.hh | 8 ++++++++ core/concept/point.hh | 8 ++++++++ core/concept/psite.hh | 26 ++++++++++++++++++++++++++ core/exact.hh | 27 +++++++++++++++++++++++++-- core/macros.hh | 3 +++ core/ops.hh | 34 +++++++++++++++++++++++++++++++++- mlc/equal.hh | 2 -- 9 files changed, 152 insertions(+), 8 deletions(-) Index: core/macros.hh --- core/macros.hh (revision 990) +++ core/macros.hh (working copy) @@ -1,6 +1,9 @@ #ifndef MLN_CORE_MACROS_HH # define MLN_CORE_MACROS_HH +/*! \file mln/core/macros.hh + * This file defines the set of milena macros. + */ # define mln_point(T) typename T::point # define mln_dpoint(T) typename T::dpoint Index: core/concept/genpoint.hh --- core/concept/genpoint.hh (revision 990) +++ core/concept/genpoint.hh (working copy) @@ -1,6 +1,10 @@ #ifndef MLN_CORE_CONCEPT_GENPOINT_HH # define MLN_CORE_CONCEPT_GENPOINT_HH +/*! \file mln/core/concept/genpoint.hh + * This file defines the concept of mln::GenPoint. + */ + # include <core/concept/object.hh> # include <core/macros.hh> # include <mlc/equal.hh> @@ -10,9 +14,20 @@ namespace mln { + /*! Base class for implementation classes that are points or that + * have the behavior of points. + * + * "GenPoint" is "General Point" for short. + * + * This class does not derive from mln::Object; it is for use as a + * parallel hierarchy. + * + * \relates mln::doc::GenPoint + */ template <typename E> struct GenPoint // stand-alone class! { + /* typedef point; typedef dpoint; @@ -31,6 +46,9 @@ }; + + /*! \relates mln::GenPoint + */ template <typename Pl, typename Pr> bool operator=(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); @@ -38,12 +56,12 @@ bool operator<(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); template <typename Pl, typename Pr> - mln_dpoint(Pl) + typename Pl::dpoint operator-(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs); template <typename P> - mln_point(P) - operator+(const GenPoint<P>& lhs, const mln_dpoint(P)& rhs); + typename P::point + operator+(const GenPoint<P>& lhs, const typename P::dpoint& rhs); template <typename P> std::ostream& operator<<(std::ostream& ostr, const GenPoint<P>& p); Index: core/concept/psite.hh --- core/concept/psite.hh (revision 990) +++ core/concept/psite.hh (working copy) @@ -1,12 +1,38 @@ #ifndef MLN_CORE_CONCEPT_PSITE_HH # define MLN_CORE_CONCEPT_PSITE_HH +/*! \file mln/core/concept/psite.hh + * This file defines the concept of mln::Psite. + */ + # include <core/concept/genpoint.hh> namespace mln { + /*! 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 + * is either a point or designates a point: regular points, deriving + * from mln::Point, are point sites, yet some point sites are not + * points.) A point site has the behavior expected from every + * point; see mln::GenPoint. + * + * When a point site is not a point, it is automatically convertible + * to the point it designates. + * + * + * Let us take the example of a 2D image encoded as an array of runs + * of values. With a point, a pair (row index, column index), + * retrieving the corresponding pixel value would mean to browse the + * array of runs to find the value location. That would not be + * efficient. Conversely, a point site dedicated to this image + * structure allows for value access in contant time; precisely the + * proper point site is a pair (index of run, index within the run). + */ template <typename E> struct Psite : public Object<E>, public GenPoint<E> Index: core/concept/object.hh --- core/concept/object.hh (revision 990) +++ core/concept/object.hh (working copy) @@ -1,6 +1,10 @@ #ifndef MLN_CORE_CONCEPT_OBJECT_HH # define MLN_CORE_CONCEPT_OBJECT_HH +/*! \file mln/core/concept/object.hh + * This file contains the top milena class. + */ + # include <cassert> # include <iostream> @@ -10,6 +14,10 @@ namespace mln { + /*! \brief Base class for almost every class defined in milena. + * + * The parameter \a E is the exact type. + */ template <typename E> struct Object { Index: core/concept/doc/genpoint.hh --- core/concept/doc/genpoint.hh (revision 0) +++ core/concept/doc/genpoint.hh (revision 0) @@ -0,0 +1,28 @@ +/*! \file mln/core/concept/genpoint.doc.hh + * This file documents the concept of mln::GenPoint. + */ + +namespace mln +{ + + namespace doc + { + + template <typename E> + struct GenPoint + { + typedef void point; ///< Associated type of point. + + typedef void dpoint; + typedef void coord; + // typedef void topo; + + operator point() const; + + const point* pointer() const; + coord operator[](unsigned i) const; + }; + + } // end of namespace mln::doc + +} // end of namespace mln Index: core/concept/point.hh --- core/concept/point.hh (revision 990) +++ core/concept/point.hh (working copy) @@ -1,12 +1,20 @@ #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. + */ + # include <core/concept/psite.hh> namespace mln { + /*! Base class for implementation of point. + * + * A point is + */ template <typename P> struct Point : public Psite<P> { Index: core/ops.hh --- core/ops.hh (revision 990) +++ core/ops.hh (working copy) @@ -1,6 +1,10 @@ #ifndef MLN_CORE_OPS_HH # define MLN_CORE_OPS_HH +/*! \file mln/core/ops.hh + * Default definitions of some operators. + */ + # include <core/concept/object.hh> # include <core/exact.hh> @@ -8,15 +12,43 @@ namespace mln { + /*! The "not equal to" operator is here defined for every milena + * objects. It relies on the definition of the "equal to" operator. + * It returns "not (lhs = rhs)". + * + * \warning There shall not be any other definition of this operator + * in milena when applying on a couple of mln::Object. + */ template <typename O1, typename O2> bool operator!=(const Object<O1>& lhs, const Object<O2>& rhs); + /*! The "greater than" operator is here defined for every milena + * objects. It relies on the definition of the "less than" + * operator. It returns "rhs < lhs". + * + * \warning There shall not be any other definition of this operator + * in milena when applying on a couple of mln::Object. + */ template <typename O1, typename O2> bool operator>(const Object<O1>& lhs, const Object<O2>& rhs); + /*! The "greater than or equal to" operator is here defined for + * every milena objects. It relies on the definition of the "less + * than or equal to" operator. It returns "rhs <= lhs". + * + * \warning There shall not be any other definition of this operator + * in milena when applying on a couple of mln::Object. + */ template <typename O1, typename O2> bool operator>=(const Object<O1>& lhs, const Object<O2>& rhs); + /*! A default version of the "less than or equal to" operator is + * defined for every milena objects. It relies on the definition of + * the "less than" operator. It returns "not (rhs < lhs)". + * + * \warning In the case of partial ordering between objects, this + * operator has to be re-defined. + */ template <typename O1, typename O2> bool operator<=(const Object<O1>& lhs, const Object<O2>& rhs); @@ -45,7 +77,7 @@ bool operator<=(const Object<O1>& lhs, const Object<O2>& rhs) { // if partial ordering, this operator should be re-defined! - return not exact(rhs) < exact(lhs); + return not (exact(rhs) < exact(lhs)); } # endif // ! MLN_INCLUDE_ONLY Index: core/exact.hh --- core/exact.hh (revision 990) +++ core/exact.hh (working copy) @@ -1,13 +1,24 @@ #ifndef MLN_CORE_EXACT_HH # define MLN_CORE_EXACT_HH +/*! \file mln/core/exact.hh + * This file defines the mln::exact downcast routines. + */ + # include <core/concept/object.hh> namespace mln { - // exact + /*! The mln::exact routine downcasts an object towards its exact + * type. + * + * The only argument is an mln::Object. The return follows the + * nature of the argument (either a pointer or a reference, const or + * not). + */ + /// \{ template <typename E> E* exact(Object<E>* ptr); @@ -21,8 +32,18 @@ template <typename E> const E& exact(const Object<E>& ref); + /// \} - // force_exact + + + /*! The mln::force_exact is a violent cast routine. + * + * It preserves the nature (pointer or reference, const or mutable) + * of its argument. The parameter \a E should not have qualifiers. + * + * \todo Move into mln::internal. + */ + /// \{ template <typename E, typename O> E* force_exact(O* ptr); @@ -36,6 +57,8 @@ template <typename E, typename O> const E& force_exact(const O& ref); + /// \} + # ifndef MLN_INCLUDE_ONLY Index: mlc/equal.hh --- mlc/equal.hh (revision 990) +++ mlc/equal.hh (working copy) @@ -1,8 +1,6 @@ #ifndef MLN_MLC_EQUAL_HH # define MLN_MLC_EQUAL_HH -# include <core/concept/genpoint.hh> - namespace mln {