[Olena-patches] 996: Add extra documentation in milena.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Thierry Geraud <thierry.geraud@lrde.epita.fr> Add extra documentation in milena. * mln/core/window2d.cc, * mln/core/window2d_qiter.cc: Remove; obsolete. * mln/core/neighb2d.hh, * mln/core/dpoint2d.hh, * mln/core/dpoints_piter.hh, * mln/core/macros.hh, * mln/core/point.hh, * mln/core/rectangle2d.hh, * mln/core/box_piter.hh, * mln/core/neighb.hh, * mln/core/concept/image.hh, * mln/core/concept/piter.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/doc/genpoint.hh, * mln/core/concept/doc/piter.hh, * mln/core/concept/neighborhood.hh, * mln/core/concept/window.hh, * mln/core/concept/box.hh, * mln/core/concept/point.hh, * mln/core/concept/iterator.hh, * mln/core/concept/dpoint.hh, * mln/core/window2d.hh, * mln/core/dpoint.hh, * mln/core/exact.hh, * mln/core/window.hh, * mln/core/contract.hh, * mln/core/internal/coord_impl.hh, * mln/core/internal/image_adaptor.hh, * mln/core/internal/image_base.hh, * mln/core/internal/set_of.hh, * mln/core/box2d.hh, * mln/core/point2d.hh: Add some documentation. box2d.hh | 16 +-- box_piter.hh | 201 +++++++++++++++++++++++++++++++++++++--------- concept/box.hh | 2 concept/doc/genpoint.hh | 11 +- concept/doc/piter.hh | 12 +- concept/dpoint.hh | 2 concept/genpoint.hh | 4 concept/image.hh | 2 concept/iterator.hh | 2 concept/neighborhood.hh | 2 concept/object.hh | 4 concept/piter.hh | 21 +++- concept/point.hh | 3 concept/point_set.hh | 2 concept/psite.hh | 2 concept/window.hh | 2 contract.hh | 9 +- dpoint.hh | 4 dpoint2d.hh | 8 - dpoints_piter.hh | 36 ++++++++ exact.hh | 2 internal/coord_impl.hh | 10 ++ internal/image_adaptor.hh | 33 ++++++- internal/image_base.hh | 26 +++++ internal/set_of.hh | 98 ++++++++++++++++++++++ macros.hh | 48 +++++++++- neighb.hh | 34 +++++++ neighb2d.hh | 2 point.hh | 4 point2d.hh | 6 - rectangle2d.hh | 63 +++++++++++++- window.hh | 34 +++++++ window2d.hh | 6 - 33 files changed, 608 insertions(+), 103 deletions(-) Index: mln/core/neighb2d.hh --- mln/core/neighb2d.hh (revision 995) +++ mln/core/neighb2d.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/neighb2d.hh * - * \brief This file defines the mln::neighb2d alias and some classical + * \brief Definition of the mln::neighb2d alias and of some classical * 2D neighborhoods. */ Index: mln/core/dpoint2d.hh --- mln/core/dpoint2d.hh (revision 995) +++ mln/core/dpoint2d.hh (working copy) @@ -3,8 +3,8 @@ /*! \file mln/core/dpoint2d.hh * - * \brief This file defines the mln::dpoint2d alias and its creation - * routine. + * \brief Definition of the mln::dpoint2d alias and of its + * construction routine. */ # include <mln/core/dpoint.hh> @@ -19,12 +19,12 @@ typedef dpoint_<2,int> dpoint2d; - /*! \brief Create a 2D delta-point. + /*! \brief Create an mln::dpoint2d. * * \param[in] row Index of row. * \param[in] col Index of column. * - * \return A dpoint2d. + * \return A 2D delta-point. */ dpoint2d mk_dpoint2d(int row, int col) { Index: mln/core/dpoints_piter.hh --- mln/core/dpoints_piter.hh (revision 995) +++ mln/core/dpoints_piter.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_DPOINTS_PITER_HH # define MLN_CORE_DPOINTS_PITER_HH +/*! \file mln/core/dpoints_piter.hh + * + * \brief Definition of mln::dpoints_fwd_piter and mln::dpoints_bkd_piter. + */ + # include <mln/core/concept/piter.hh> # include <mln/core/concept/genpoint.hh> @@ -8,30 +13,59 @@ namespace mln { + /*! \brief A generic forward iterator on points of windows and of + * neighborhoods. + * + * The parameter \c D is the type of delta-points. + */ template <typename D> class dpoints_fwd_piter : public Piter< dpoints_fwd_piter<D> > { public: + /// Space dimension. enum { dim = D::dim }; + /// Dpoint associated type. typedef D dpoint; + + /// Point associated type. typedef mln_point(D) point; + + /// Psite associated type. typedef point psite; + + /// Coordinate associated type. typedef mln_coord(D) coord; + /*! \brief Constructor. + * + * \param[in] dps Object that can provide an array of delta-points. + * \param[in] p_ref Center point to iterate around. + */ template <typename Dps, typename Pref> dpoints_fwd_piter(const Dps& dps, const GenPoint<Pref>& p_ref); - operator point() const; + /// Convertion to point. + operator mln_point(D) () const; + + /// Address of the point. const point* pointer() const; + /// Test the iterator validity. bool is_valid() const; + + /// Invalidate the iterator. void invalidate(); + + /// Start an iteration. void start(); + + /// Go to the next point. void next_(); + /// Give the i-th coordinate. coord operator[](unsigned i) const; private: Index: mln/core/macros.hh --- mln/core/macros.hh (revision 995) +++ mln/core/macros.hh (working copy) @@ -2,42 +2,74 @@ # define MLN_CORE_MACROS_HH /*! \file mln/core/macros.hh - * This file defines the set of milena macros. + * Definition of the set of milena macros. */ -/*! \def mln_point - */ -# define mln_point typename T::point +/// \brief Shortcut to access the point type associated to T. +# define mln_point(T) typename T::point -/*! \def mln_dpoint - */ +/// \brief Shortcut to access the dpoint type associated to T. # define mln_dpoint(T) typename T::dpoint +/// \brief Shortcut to access the psite type associated to T. # define mln_psite(T) typename T::psite + +/// \brief Shortcut to access the pset type associated to T. # define mln_pset(T) typename T::pset + +/// \brief Shortcut to access the box type associated to T. # define mln_box(T) typename T::box -/*! \def mln_coord(T) - */ +/// \brief Shortcut to access the coord type associated to T. # define mln_coord(T) typename T::coord + +/// \brief Shortcut to access the piter type associated to T. # define mln_piter(T) typename T::piter + +/// \brief Shortcut to access the fwd_piter type associated to T. # define mln_fwd_piter(T) typename T::fwd_piter + +/// \brief Shortcut to access the bkd_piter type associated to T. # define mln_bkd_piter(T) typename T::bkd_piter + +/// \brief Shortcut to access the qiter type associated to T. # define mln_qiter(T) typename T::qiter + +/// \brief Shortcut to access the fwd_qiter type associated to T. # define mln_fwd_qiter(T) typename T::fwd_qiter + +/// \brief Shortcut to access the bkd_qiter type associated to T. # define mln_bkd_qiter(T) typename T::bkd_qiter + +/// \brief Shortcut to access the niter type associated to T. # define mln_niter(T) typename T::niter + +/// \brief Shortcut to access the fwd_niter type associated to T. # define mln_fwd_niter(T) typename T::fwd_niter + +/// \brief Shortcut to access the bkd_niter type associated to T. # define mln_bkd_niter(T) typename T::bkd_niter + +/// \brief Shortcut to access the value type associated to T. # define mln_value(T) typename T::value + +/// \brief Shortcut to access the rvalue type associated to T. # define mln_rvalue(T) typename T::rvalue + +/// \brief Shortcut to access the lvalue type associated to T. # define mln_lvalue(T) typename T::lvalue + +/*! \brief Shortcut to change the value type of an image type. + * + * \c I is an image type + * \c T is the new value type + */ # define mln_ch_value(I, T) typename I::template change_value<T>::ret Index: mln/core/point.hh --- mln/core/point.hh (revision 995) +++ mln/core/point.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/point.hh * - * \brief This file defines a generic point class. + * \brief Definition of the generic point class mln::point_. */ # include <mln/core/concept/point.hh> @@ -36,7 +36,7 @@ */ typedef dpoint_<n,C> dpoint; - /*! Coordinate associated type. + /*! \brief Coordinate associated type. */ typedef C coord; Index: mln/core/rectangle2d.hh --- mln/core/rectangle2d.hh (revision 995) +++ mln/core/rectangle2d.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_RECTANGLE2D_HH # define MLN_CORE_RECTANGLE2D_HH +/*! \file mln/core/rectangle2d.hh + * + * \brief Definition of the mln::rectangle2d window. + */ + # include <mln/core/concept/window.hh> # include <mln/core/internal/set_of.hh> # include <mln/core/dpoint2d.hh> @@ -10,28 +15,80 @@ namespace mln { - // FIXME: doc. + /*! \brief Rectangular window defined on the 2D square grid. + * + * A rectangle2d is a 2D window with rectangular shape. It is + * centered and symmetrical. + * + * For instance: + * o o o o o + * o o x o o + * o o o o o + * is defined with half_height = 1 and half_width = 2. + */ struct rectangle2d : public Window< rectangle2d >, public internal::set_of_<dpoint2d> { + /*! \brief Piter type to browse a rectangle such as: "for each row + * (increasing), for each column (increasing)." + */ typedef dpoints_fwd_piter<dpoint2d> fwd_qiter; + + /*! \brief Piter type to browse a rectangle such as: "for each row + * (decreasing), for each column (decreasing)." + */ typedef dpoints_bkd_piter<dpoint2d> bkd_qiter; + + /*! \brief Same as fwd_qiter. + */ typedef fwd_qiter qiter; + /*! \brief Constructor. + * + * \param[in] half_height sic + * \param[in] half_width sic + * + * \pre half_height != 0 and half_width != 0 + */ rectangle2d(unsigned half_height, unsigned half_width); + /*! \brief Test if the window is centered. + * + * \return True. + */ bool is_centered() const; + + /*! \brief Test if the window is symmetric. + * + * \return true. + */ bool is_symmetric() const; + /*! \brief Give the rectangle height. + */ unsigned height() const; + + /*! \brief Give the rectangle width. + */ unsigned width() const; protected: unsigned half_height_, half_width_; }; - std::ostream& operator<<(std::ostream& ostr, - const rectangle2d& win); + + /*! \brief Print a rectangle window \p win into the output stream \p + * ostr. + * + * \param[in,out] ostr An output stream. + * \param[in] win A rectangle window. + * + * \return The modified output stream \p ostr. + * + * \relates mln::rectangle2d + */ + std::ostream& operator<<(std::ostream& ostr, const rectangle2d& win); + # ifndef MLN_INCLUDE_ONLY Index: mln/core/box_piter.hh --- mln/core/box_piter.hh (revision 995) +++ mln/core/box_piter.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_BOX_PITER_HH # define MLN_CORE_BOX_PITER_HH +/*! \file mln/core/box_piter.hh + * + * \brief Definition of iterators on points of boxes. + */ + # include <mln/core/concept/piter.hh> # include <mln/core/concept/box.hh> @@ -8,19 +13,134 @@ namespace mln { + /*! \brief A generic forward iterator on points of boxes. + * + * The parameter \c P is the type of points. + * + * \see mln::box_ + */ template <typename P> class box_fwd_piter_ : public Piter< box_fwd_piter_<P> > { public: + /// Space dimension. enum { dim = P::dim }; + /// Psite associated type. typedef P psite; + + /// Point associated type. typedef P point; + + /// Dpoint associated type. + typedef mln_dpoint(P) dpoint; + + /// Coordinate associated type. typedef mln_coord(P) coord; + + /*! \brief Constructor. + * + * \param[in] b A box. + */ + box_fwd_piter_(const box_<P>& b); + + /// Convertion to point. + operator P() const; + + /// Address of the point. + const P* pointer() const; + + /// Give the i-th coordinate. + coord operator[](unsigned i) const; + + /// Test the iterator validity. + bool is_valid() const; + + /// Invalidate the iterator. + void invalidate(); + + /// Start an iteration. + void start(); + + /// Go to the next point. + void next_(); + + private: + const box_<P>& b_; + P p_, nop_; + }; + + + + /*! \brief A generic backward iterator on points of boxes. + * + * The parameter \c P is the type of points. + * + * \see mln::box_ + */ + template <typename P> + class box_bkd_piter_ : public Piter< box_bkd_piter_<P> > + { + public: + + /// Space dimension. + enum { dim = P::dim }; + + /// Psite associated type. + typedef P psite; + + /// Point associated type. + typedef P point; + + /// Dpoint associated type. typedef mln_dpoint(P) dpoint; - box_fwd_piter_(const box_<P>& b) + /// Coordinate associated type. + typedef mln_coord(P) coord; + + /*! \brief Constructor. + * + * \param[in] b A box. + */ + box_bkd_piter_(const box_<P>& b); + + /// Convertion to point. + operator P() const; + + /// Address of the point. + const P* pointer() const; + + /// Give the i-th coordinate. + coord operator[](unsigned i) const; + + /// Test the iterator validity. + bool is_valid() const; + + /// Invalidate the iterator. + void invalidate(); + + /// Start an iteration. + void start(); + + /// Go to the next point. + void next_(); + + private: + const box_<P>& b_; + P p_, nop_; + }; + + + + +# ifndef MLN_INCLUDE_ONLY + + + // box_fwd_piter_<P> + + template <typename P> + box_fwd_piter_<P>::box_fwd_piter_(const box_<P>& b) : b_(b) { nop_ = b_.pmax(); @@ -28,38 +148,51 @@ invalidate(); } - operator P() const + template <typename P> + box_fwd_piter_<P>::operator P() const { return p_; } - const P* pointer() const + template <typename P> + const P* + box_fwd_piter_<P>::pointer() const { return & p_; } - coord operator[](unsigned i) const + template <typename P> + mln_coord(P) + box_fwd_piter_<P>::operator[](unsigned i) const { assert(i < dim); return p_[i]; } - bool is_valid() const + template <typename P> + bool + box_fwd_piter_<P>::is_valid() const { return p_ != nop_; } - void invalidate() + template <typename P> + void + box_fwd_piter_<P>::invalidate() { p_ = nop_; } - void start() + template <typename P> + void + box_fwd_piter_<P>::start() { p_ = b_.pmin(); } - void next_() + template <typename P> + void + box_fwd_piter_<P>::next_() { for (int i = dim - 1; i >= 0; --i) if (p_[i] = b_.pmax()[i]) @@ -73,25 +206,11 @@ p_ = nop_; } - private: - const box_<P>& b_; - P p_, nop_; - }; - + // box_bkd_piter_<P> template <typename P> - class box_bkd_piter_ : public Piter< box_bkd_piter_<P> > - { - public: - - enum { dim = P::dim }; - - typedef P psite; - typedef P point; - typedef mln_coord(P) coord; - - box_bkd_piter_(const box_<P>& b) + box_bkd_piter_<P>::box_bkd_piter_(const box_<P>& b) : b_(b) { nop_ = b_.pmin(); @@ -99,38 +218,52 @@ invalidate(); } - operator P() const + template <typename P> + box_bkd_piter_<P>::operator P() const { return p_; } - const P* pointer() const + + template <typename P> + const P* + box_bkd_piter_<P>::pointer() const { return & p_; } - coord operator[](unsigned i) const + template <typename P> + mln_coord(P) + box_bkd_piter_<P>::operator[](unsigned i) const { assert(i < dim); return p_[i]; } - bool is_valid() const + template <typename P> + bool + box_bkd_piter_<P>::is_valid() const { return p_ != nop_; } - void invalidate() + template <typename P> + void + box_bkd_piter_<P>::invalidate() { p_ = nop_; } - void start() + template <typename P> + void + box_bkd_piter_<P>::start() { p_ = b_.pmax(); } - void next_() + template <typename P> + void + box_bkd_piter_<P>::next_() { for (int i = dim - 1; i >= 0; --i) if (p_[i] = b_.pmin()[i]) @@ -144,11 +277,7 @@ p_ = nop_; } - private: - const box_<P>& b_; - P p_, nop_; - }; - +# endif // ! MLN_INCLUDE_ONLY } // end of namespace mln Index: mln/core/neighb.hh --- mln/core/neighb.hh (revision 995) +++ mln/core/neighb.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_NEIGHB_HH # define MLN_CORE_NEIGHB_HH +/*! \file mln/core/neighb.hh + * + * \brief Definition of the generic neighborhood class mln::neighb_. + */ + # include <mln/core/concept/neighborhood.hh> # include <mln/core/internal/set_of.hh> # include <mln/core/dpoint.hh> @@ -14,16 +19,45 @@ template <typename D> class dpoints_bkd_piter; + /*! \brief Generic neighborhood class. + * + * This neighborhood of window is just like a set of delta-points. + * The parameter is \c D, type of delta-point. + */ template <typename D> struct neighb_ : public Neighborhood< neighb_<D> >, public internal::set_of_<D> { + /*! \brief Piter type to browse the points of a generic + * neighborhood w.r.t. the ordering of delta-points. + */ typedef dpoints_fwd_piter<D> fwd_niter; + + /*! \brief Piter type to browse the points of a generic + * neighborhood w.r.t. the reverse ordering of delta-points. + */ typedef dpoints_bkd_piter<D> bkd_niter; + + /*! \brief Same as fwd_niter. + */ typedef fwd_niter niter; + /*! \brief Constructor without argument. + * + * The constructed neighborhood is empty. You have to use insert() + * to proceed to the neighborhood definition. + */ neighb_(); + /*! \brief Insert a delta-point \p dp in the neighborhood + * definition. + * + * \param[in] dp The delta-point to insert. + * + * This method also insert the symmetrical delta-point, - \p dp, + * in the neighborhood definition; thus the client has not to + * ensure the symmetry property; that is automatic. + */ void insert(const D& dp); }; Index: mln/core/concept/image.hh --- mln/core/concept/image.hh (revision 995) +++ mln/core/concept/image.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_IMAGE_HH /*! \file mln/core/concept/image.hh - * \brief This file defines the concept of mln::Image. + * \brief Definition of the concept of mln::Image. */ # include <mln/core/concept/point_set.hh> Index: mln/core/concept/piter.hh --- mln/core/concept/piter.hh (revision 995) +++ mln/core/concept/piter.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_CONCEPT_PITER_HH # define MLN_CORE_CONCEPT_PITER_HH +/*! \file mln/core/concept/piter.hh + * + * \brief Definition of the concept of mln::Piter. + */ + # include <mln/core/concept/iterator.hh> # include <mln/core/concept/genpoint.hh> @@ -8,17 +13,22 @@ namespace mln { + /*! \brief Base class for implementation of classes of iterator on + * points. + * + * An iterator on points is an iterator that browse over a set of + * points. + * + * \see mln::doc::Piter for a complete documentation of this class + * contents. + */ template <typename E> struct Piter : public Iterator<E>, public GenPoint<E> { /* typedef psite; - typedef point; - operator psite() const; - operator point() const; - const point* pointer() const; */ protected: @@ -32,8 +42,7 @@ Piter<E>::Piter() { typedef mln_psite(E) psite; - typedef mln_point(E) point; - const point* (E::*m)() const = & E::pointer; + psite (E::*m)() const = & E::operator psite; m = 0; } Index: mln/core/concept/genpoint.hh --- mln/core/concept/genpoint.hh (revision 995) +++ mln/core/concept/genpoint.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_GENPOINT_HH /*! \file mln/core/concept/genpoint.hh - * \brief This file defines the concept of mln::GenPoint. + * \brief Definition of the concept of mln::GenPoint. */ # include <mlc/equal.hh> # include <mlc/same_point.hh> @@ -163,7 +163,7 @@ GenPoint<E>::GenPoint() { const int dim = E::dim; - invariant(dim > 0); + mln_invariant(dim > 0); typedef mln_point(E) point; typedef mln_dpoint(E) dpoint; typedef mln_coord(E) coord; Index: mln/core/concept/point_set.hh --- mln/core/concept/point_set.hh (revision 995) +++ mln/core/concept/point_set.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_POINT_SET_HH /*! \file mln/core/concept/point_set.hh - * \brief This file defines the concept of mln::Point_Set. + * \brief Definition of the concept of mln::Point_Set. */ # include <mln/core/concept/point.hh> Index: mln/core/concept/psite.hh --- mln/core/concept/psite.hh (revision 995) +++ mln/core/concept/psite.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_PSITE_HH /*! \file mln/core/concept/psite.hh - * \brief This file defines the concept of mln::Psite. + * \brief Definition of the concept of mln::Psite. */ # include <mln/core/concept/genpoint.hh> Index: mln/core/concept/object.hh --- mln/core/concept/object.hh (revision 995) +++ mln/core/concept/object.hh (working copy) @@ -2,13 +2,15 @@ # define MLN_CORE_CONCEPT_OBJECT_HH /*! \file mln/core/concept/object.hh - * \brief This file contains the top milena class. + * + * \brief Definition of the top milena class mln::Object. */ # include <cassert> # include <iostream> # include <mln/core/macros.hh> +# include <mln/core/contract.hh> /*! \namespace mln Index: mln/core/concept/doc/genpoint.hh --- mln/core/concept/doc/genpoint.hh (revision 995) +++ mln/core/concept/doc/genpoint.hh (working copy) @@ -36,11 +36,16 @@ typedef void coord; - // FIXME: - // typedef void topo; - // operator point() const; + // FIXME: typedef void topo; + /*! \brief Either \c E is a point or an convertion operator into + * a point is defined. + * + * \return A point. + */ + operator point() const; + /*! \brief Give a hook to the point address. * * This method allows for iterators to refer to a point. Index: mln/core/concept/doc/piter.hh --- mln/core/concept/doc/piter.hh (revision 995) +++ mln/core/concept/doc/piter.hh (working copy) @@ -9,19 +9,23 @@ { /*! \brief Documentation class for mln::Piter. + * * \see mln::Piter */ template <typename E> struct Piter : public Iterator<E>, public GenPoint<E> { - // FIXME: HERE + /*! \brief Psite associated type. + * \invariant This type has to derive from mln::Psite. + */ typedef void psite; - typedef void point; + /*! \brief Convertion into a point-site. + * + * \return A point site. + */ operator psite() const; - operator point() const; - const point* pointer() const; }; } // end of namespace mln::doc Index: mln/core/concept/neighborhood.hh --- mln/core/concept/neighborhood.hh (revision 995) +++ mln/core/concept/neighborhood.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_NEIGHBORHOOD_HH /*! \file mln/core/concept/neighborhood.hh - * \brief This file defines the concept of mln::Neighborhood. + * \brief Definition of the concept of mln::Neighborhood. */ # include <mln/core/concept/object.hh> Index: mln/core/concept/window.hh --- mln/core/concept/window.hh (revision 995) +++ mln/core/concept/window.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_WINDOW_HH /*! \file mln/core/concept/window.hh - * \brief This file defines the concept of mln::Window. + * \brief Definition of the concept of mln::Window. */ # include <mln/core/concept/object.hh> Index: mln/core/concept/box.hh --- mln/core/concept/box.hh (revision 995) +++ mln/core/concept/box.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_BOX_HH /*! \file mln/core/concept/box.hh - * \brief This file defines the concept of mln::Box. + * \brief Definition of the concept of mln::Box. */ # include <mln/core/concept/point_set.hh> Index: mln/core/concept/point.hh --- mln/core/concept/point.hh (revision 995) +++ mln/core/concept/point.hh (working copy) @@ -2,7 +2,8 @@ # define MLN_CORE_CONCEPT_POINT_HH /*! \file mln/core/concept/point.hh - * \brief This file defines the concept of mln::Point. + * + * \brief Definition of the concept of mln::Point. */ # include <mln/core/concept/psite.hh> Index: mln/core/concept/iterator.hh --- mln/core/concept/iterator.hh (revision 995) +++ mln/core/concept/iterator.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_ITERATOR_HH /*! \file mln/core/concept/iterator.hh - * \brief This file defines the concept of mln::Iterator. + * \brief Definition of the concept of mln::Iterator. */ # include <mln/core/concept/object.hh> Index: mln/core/concept/dpoint.hh --- mln/core/concept/dpoint.hh (revision 995) +++ mln/core/concept/dpoint.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_CONCEPT_DPOINT_HH /*! \file mln/core/concept/dpoint.hh - * \brief This file defines the concept of mln::Dpoint. + * \brief Definition of the concept of mln::Dpoint. */ # include <mln/core/concept/object.hh> Index: mln/core/window2d.hh --- mln/core/window2d.hh (revision 995) +++ mln/core/window2d.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/window2d.hh * - * \brief This file defines the mln::window2d alias and its creation + * \brief Definition of the mln::window2d alias and of a construction * routine. */ @@ -21,13 +21,13 @@ typedef window_<dpoint2d> window2d; - /*! \brief Create a 2D window with arbitrary shape. + /*! \brief Create an mln::window2d. * * \param[in] values Array of Booleans. * * \pre The array size, \c M, has to be a square of an odd integer. * - * \return A window2d. + * \return A 2D window. */ template <unsigned M> window2d mk_window2d(const bool (&values)[M]); Index: mln/core/dpoint.hh --- mln/core/dpoint.hh (revision 995) +++ mln/core/dpoint.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/dpoint.hh * - * \brief This file defines a generic delta-point class. + * \brief Definition of the generic delta-point class mln::dpoint_. */ # include <mln/core/concept/dpoint.hh> @@ -36,7 +36,7 @@ */ typedef point_<n,C> point; - /*! Coordinate associated type. + /*! \brief Coordinate associated type. */ typedef C coord; Index: mln/core/exact.hh --- mln/core/exact.hh (revision 995) +++ mln/core/exact.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_EXACT_HH /*! \file mln/core/exact.hh - * \brief This file defines the mln::exact downcast routines. + * \brief Definition of the mln::exact downcast routines. */ # include <mln/core/concept/object.hh> Index: mln/core/window.hh --- mln/core/window.hh (revision 995) +++ mln/core/window.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_WINDOW_HH # define MLN_CORE_WINDOW_HH +/*! \file mln/core/window.hh + * + * \brief Definition of the generic window class mln::window_. + */ + # include <mln/core/concept/window.hh> # include <mln/core/internal/set_of.hh> # include <mln/core/dpoint.hh> @@ -14,21 +19,50 @@ template <typename D> class dpoints_bkd_piter; + /*! \brief Generic window class. + * + * This type of window is just like a set of delta-points. The + * parameter is \c D, type of delta-point. + */ template <typename D> struct window_ : public Window< window_<D> >, public internal::set_of_<D> { + /*! \brief Piter type to browse the points of a generic window + * w.r.t. the ordering of delta-points. + */ typedef dpoints_fwd_piter<D> fwd_qiter; + + /*! \brief Piter type to browse the points of a generic window + * w.r.t. the reverse ordering of delta-points. + */ typedef dpoints_bkd_piter<D> bkd_qiter; + + /*! \brief Same as fwd_qiter. + */ typedef fwd_qiter qiter; + /*! \brief Constructor without argument. + * + * The constructed window is empty. + */ window_(); + /*! \brief Test if the window is centered. + * + * \return True if the delta-point 0 belongs to the window. + */ bool is_centered() const; + + /*! \brief Test if the window is symmetric. + * + * \todo Implementation! + */ bool is_symmetric() const; }; + # ifndef MLN_INCLUDE_ONLY template <typename D> Index: mln/core/contract.hh --- mln/core/contract.hh (revision 995) +++ mln/core/contract.hh (working copy) @@ -2,18 +2,25 @@ # define MLN_CORE_CONTRACT_HH /*! \file mln/core/contract.hh - * This file defines the set of contracts. + * Definition of the set of contracts. */ # include <cassert> +/// Assertion. # define mln_assertion(expr) assert(expr) +/// Invariant. # define mln_invariant(expr) assert(expr) + +/// Precondition. # define mln_precondition(expr) assert(expr) + +/// Postcondition. # define mln_postcondition(expr) assert(expr) +/// Implication. # define mln_implies(lexpr, repxr) assert(not (rexpr) or (lexpr)) Index: mln/core/internal/coord_impl.hh --- mln/core/internal/coord_impl.hh (revision 995) +++ mln/core/internal/coord_impl.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_INTERNAL_COORD_IMPL_HH # define MLN_CORE_INTERNAL_COORD_IMPL_HH +/*! \file mln/core/internal/coord_impl.hh + * + * \brief Define some implementation classes for generalized points. + */ + # include <mln/core/concept/object.hh> @@ -12,6 +17,11 @@ // coord_impl + /*! \brief Implementation class to equip generalized points with + * explicit access to their coordinates. + * + * \internal + */ template <unsigned n, typename C, typename E> struct coord_impl_; Index: mln/core/internal/image_adaptor.hh --- mln/core/internal/image_adaptor.hh (revision 995) +++ mln/core/internal/image_adaptor.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_INTERNAL_IMAGE_ADAPTOR_HH # define MLN_CORE_INTERNAL_IMAGE_ADAPTOR_HH +/*! \file mln/core/internal/image_adaptor.hh + * + * \brief Definition of a base class for image adaptors. + */ + # include <mln/core/internal/image_base.hh> @@ -10,32 +15,54 @@ namespace internal { + /*! \brief A base class for image adaptors. + * + * \internal + */ template <typename I, typename E> struct image_adaptor_ : public internal::image_base_< mln_pset(I), E > { + /// Psite associated type. typedef mln_psite(I) psite; + + /// Point_Set associated type. typedef mln_pset(I) pset; + /// Value associated type. typedef mln_value(I) value; + + /// Return type of read-only access. typedef mln_rvalue(I) rvalue; + + /// Return type of read-write access. typedef mln_lvalue(I) lvalue; + /// Test if this image has been initialized. bool has_data() const; + /// Test if a pixel value is accessible at \p p. bool owns_(const psite& p) const; + + /// Give the definition domain. const pset& domain() const; + /// Read-only access of pixel value at point site \p p. rvalue operator()(const psite& p) const; + + /// Read-write access of pixel value at point site \p p. lvalue operator()(const psite& p); protected: I& adaptee_; + + /// Constructor from an \p adaptee image. image_adaptor_(Image<I>& adaptee); }; // FIXME: image_const_adaptor_ + # ifndef MLN_INCLUDE_ONLY template <typename I, typename E> @@ -51,21 +78,21 @@ } template <typename I, typename E> - const mln_pset(I)& + const image_adaptor_<I,E>::pset& image_adaptor_<I,E>::domain() const { return adaptee_.domain(); } template <typename I, typename E> - mln_rvalue(I) + typename image_adaptor_<I,E>::rvalue image_adaptor_<I,E>::operator()(const psite& p) const { return adaptee_(p); } template <typename I, typename E> - mln_lvalue(I) + typename image_adaptor_<I,E>::lvalue image_adaptor_<I,E>::operator()(const psite& p) { return adaptee_(p); Index: mln/core/internal/image_base.hh --- mln/core/internal/image_base.hh (revision 995) +++ mln/core/internal/image_base.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_INTERNAL_IMAGE_BASE_HH # define MLN_CORE_INTERNAL_IMAGE_BASE_HH +/*! \file mln/core/internal/image_base.hh + * + * \brief Definition of a base class for some images. + */ + # include <mln/core/concept/image.hh> @@ -10,19 +15,38 @@ namespace internal { + /*! \brief A base class for images. + * + * \internal + */ template <typename S, typename E> struct image_base_ : public Image<E> { + /// Point_Set associated type. typedef S pset; + + /// Psite associated type. typedef mln_psite(S) psite; + + /// Point associated type. typedef mln_point(S) point; + /// Forward Piter associated type. typedef mln_fwd_piter(S) fwd_piter; + + /// Backward Piter associated type. typedef mln_bkd_piter(S) bkd_piter; + + /// Piter associated type. typedef fwd_piter piter; + /// Test if \p p belongs to the image domain. bool has(const psite& p) const; - bool owns_(const psite& p) const; // default + + /// Test if a pixel value is accessible at \p p. + bool owns_(const psite& p) const; + + /// Give a bounding box of the image domain. const box_<point>& bbox() const; protected: Index: mln/core/internal/set_of.hh --- mln/core/internal/set_of.hh (revision 995) +++ mln/core/internal/set_of.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_INTERNAL_SET_OF_HH # define MLN_CORE_INTERNAL_SET_OF_HH +/*! \file mln/core/internal/set_of.hh + * + * \brief Definition of mln::set_of_ for internal use only. + */ + # include <vector> # include <set> # include <iterator> @@ -12,30 +17,121 @@ namespace internal { + + /*! \brief An "efficient" mathematical set class. + * + * \internal + * + * This set class is designed to store a mathematical set and to + * present it to the user as a linear array. + * + * Elements are stored by copy. + * + * \invariant \a v_.size() = s_.size() + * + * The parameter \c E is the element type, which shall not be + * const-qualified. + */ template <typename E> class set_of_ { public: + + /*! \brief Insert an element \p elt into the set. + * + * \param[in] elt The element to be inserted. + * + * If \p elt is already in the set, this method is a no-op. + */ void insert(const E& elt); + + + /*! \brief Return the i-th element of the set. + * + * \param[in] i Index of the element to retrieve. + * + * \pre i < nelements() + * + * The element is returned by reference and is constant. + */ const E& element(unsigned i) const; + + + /*! \brief Return the number of elements of the set. + */ unsigned nelements() const; + + + /*! \brief Test if the object \p elt belongs to the set. + * + * \param[in] elt A possible element of the set. + * + * \return True is \p elt is in the set. + */ bool has(const E& elt) const; + + + /*! \brief Test if the set is empty. + */ bool is_empty() const; + + + /*! \brief Make the set empty. + * + * All elements contained in the set are destroyed so the set is + * emptied. + * + * \post is_empty() = true + */ void clear(); + + /*! \brief Give access to the set elements. + * + * The complexity of this method is O(1). + * + * \return An array (std::vector) of elements. + */ const std::vector<E>& vec() const; + protected: + /*! \brief Array of elements. + * + * This structure is always up-to-date so that the access method + * vec is as fastest as possible. + */ std::vector<E> v_; + private: + /*! \brief Set of elements. + * + * This is an auxiliary structure. + */ std::set<E> s_; + + + /*! \brief Update both attributes. + * + * FIXME: explain. + */ void update_(); }; + /*! \brief Print a set \p s into the output stream \p + * ostr. + * + * \param[in,out] ostr An output stream. + * \param[in] s A set. + * + * \return The modified output stream \p ostr. + * + * \relates mln::internal::set_of_ + */ template <typename E> std::ostream& operator<<(std::ostream& ostr, const set_of_<E>& s); @@ -85,6 +181,7 @@ { v_.clear(); s_.clear(); + mln_postcondition(is_empty()); } template <typename E> @@ -100,6 +197,7 @@ { v_.clear(); std::copy(s_.begin(), s_.end(), std::back_inserter(v_)); + // no s_.clear() here to save some execution time } template <typename E> Index: mln/core/box2d.hh --- mln/core/box2d.hh (revision 995) +++ mln/core/box2d.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/box2d.hh * - * \brief This file defines the mln::box2d alias and construction + * \brief Definition of the mln::box2d alias and of construction * routines. */ @@ -16,11 +16,13 @@ /*! \brief Type alias for a box defined on the 2D square grid with * integer coordinates. + * + * \see mln::rectangle2d. */ typedef box_<point2d> box2d; - /*! \brief Create a 2D box. + /*! \brief Create an mln::box2d. * * \param[in] nrows Number of rows. * \param[in] ncols Number of columns. @@ -28,19 +30,17 @@ * \pre \p nrows != 0 and \p ncols != 0. * * \return A 2D box. - * - * \relates mln::box2d */ box2d mk_box2d(unsigned nrows, unsigned ncols) { - precondition(nrows != 0 and ncols != 0); + mln_precondition(nrows != 0 and ncols != 0); box2d tmp(mk_point2d(0, 0), mk_point2d(nrows - 1, ncols - 1)); return tmp; } - /*! \brief Create a 2D box. + /*! \brief Create an mln::box2d. * * \overload * @@ -52,13 +52,11 @@ * \pre \p max_row >= \p min_row and \p max_col >= \p min_col. * * \return A 2D box. - * - * \relates mln::box2d */ box2d mk_box2d(int min_row, int max_row, int min_col, int max_col) { - precondition(max_row >= min_row and max_col >= min_col); + mln_precondition(max_row >= min_row and max_col >= min_col); box2d tmp(mk_point2d(min_row, min_col), mk_point2d(max_row, max_col)); return tmp; Index: mln/core/point2d.hh --- mln/core/point2d.hh (revision 995) +++ mln/core/point2d.hh (working copy) @@ -3,7 +3,7 @@ /*! \file mln/core/point2d.hh * - * \brief This file defines the mln::point2d alias and its creation + * \brief Definition of the mln::point2d alias and of its construction * routine. */ @@ -19,12 +19,12 @@ typedef point_<2,int> point2d; - /*! \brief Create a 2D point. + /*! \brief Create an mln::point2d. * * \param[in] row Index of row. * \param[in] col Index of column. * - * \return A point2d. + * \return A 2D point. */ point2d mk_point2d(int row, int col) {