[Olena-patches] 995: Extend mln documentation.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Thierry Geraud &lt;thierry.geraud(a)lrde.epita.fr&gt; Extend mln documentation. * doc/Doxyfile.in (PREDEFINED): Handle some macros. * mln/core/neighb2d.hh, * mln/core/dpoint2d.hh, * mln/core/macros.hh, * mln/core/box.hh, * mln/core/point.hh, * mln/core/rectangle2d.hh, * mln/core/concept/image.hh, * mln/core/concept/genpoint.hh, * mln/core/concept/object.hh, * mln/core/concept/doc/image.hh, * mln/core/concept/doc/genpoint.hh, * mln/core/concept/doc/point_set.hh, * mln/core/concept/doc/object.hh, * mln/core/concept/doc/neighborhood.hh, * mln/core/concept/doc/window.hh, * mln/core/concept/doc/box.hh, * mln/core/concept/doc/iterator.hh, * mln/core/concept/doc/dpoint.hh, * mln/core/concept/neighborhood.hh, * mln/core/concept/box.hh, * mln/core/concept/point.hh, * mln/core/concept/dpoint.hh, * mln/core/window2d.hh, * mln/core/dpoint.hh, * mln/core/ops.hh, * mln/core/exact.hh, * mln/core/box2d.hh, * mln/core/point2d.hh: Add extra documentation. doc/Doxyfile.in | 10 +- mln/core/box.hh | 118 +++++++++++++++++++++++++++++++---- mln/core/box2d.hh | 39 +++++++++++ mln/core/concept/box.hh | 19 +++++ mln/core/concept/doc/box.hh | 24 +++---- mln/core/concept/doc/dpoint.hh | 33 ++++++++- mln/core/concept/doc/genpoint.hh | 3 mln/core/concept/doc/image.hh | 94 ++++++++++++++++++++++++++- mln/core/concept/doc/iterator.hh | 20 +++-- mln/core/concept/doc/neighborhood.hh | 16 ++++ mln/core/concept/doc/object.hh | 1 mln/core/concept/doc/point_set.hh | 5 - mln/core/concept/doc/window.hh | 4 + mln/core/concept/dpoint.hh | 70 +++++++++++++++++++- mln/core/concept/genpoint.hh | 37 ++++------ mln/core/concept/image.hh | 9 ++ mln/core/concept/neighborhood.hh | 9 ++ mln/core/concept/object.hh | 11 +++ mln/core/concept/point.hh | 13 ++- mln/core/dpoint.hh | 39 +++++++++++ mln/core/dpoint2d.hh | 17 +++++ mln/core/exact.hh | 24 +++++-- mln/core/macros.hh | 6 - mln/core/neighb2d.hh | 49 ++++++++++++++ mln/core/ops.hh | 23 +++++- mln/core/point.hh | 39 +++++++++++ mln/core/point2d.hh | 17 +++++ mln/core/rectangle2d.hh | 1 mln/core/window2d.hh | 18 +++++ 29 files changed, 667 insertions(+), 101 deletions(-) Index: doc/Doxyfile.in --- doc/Doxyfile.in (revision 994) +++ doc/Doxyfile.in (working copy) @@ -1041,7 +1041,10 @@ # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = \ + "mln_coord(T)=typename T::coord" \ + "mln_point(T)=typename T::point" \ + "mln_dpoint(T)=typename T::dpoint" # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES # then this tag can be used to specify a list of macro names that @@ -1049,10 +1052,7 @@ # sources will be used. Use the PREDEFINED tag if you want to use a # different macro definition. -EXPAND_AS_DEFINED = \ - mln_point \ - mln_dpoint \ - mln_coord +EXPAND_AS_DEFINED = # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then Index: mln/core/neighb2d.hh --- mln/core/neighb2d.hh (revision 994) +++ mln/core/neighb2d.hh (working copy) @@ -1,6 +1,12 @@ #ifndef MLN_CORE_NEIGHB2D_HH # define MLN_CORE_NEIGHB2D_HH +/*! \file mln/core/neighb2d.hh + * + * \brief This file defines the mln::neighb2d alias and some classical + * 2D neighborhoods. + */ + # include <cmath> # include <mln/core/neighb.hh> # include <mln/core/dpoint2d.hh> @@ -9,14 +15,57 @@ namespace mln { + /*! \brief Type alias for a neighborhood defined on the 2D square + * grid with integer coordinates. + */ typedef neighb_<dpoint2d> neighb2d; + + /*! \brief 4-connectivity neighborhood on the 2D grid. + * + * - o - + * o x o + * - o - + * + * \return A neighb2d. + */ const neighb2d& c4(); + + + /*! \brief 8-connectivity neighborhood on the 2D grid. + * + * o o o + * o x o + * o o o + * + * \return A neighb2d. + */ const neighb2d& c8(); + + + /*! \brief Horizontal 2-connectivity neighborhood on the 2D grid. + * + * - - - + * o x o + * - - - + * + * \return A neighb2d. + */ const neighb2d& c2_row(); + + + /*! \brief Vertical 2-connectivity neighborhood on the 2D grid. + * + * - o - + * - x - + * - o - + * + * \return A neighb2d. + */ const neighb2d& c2_col(); + # ifndef MLN_INCLUDE_ONLY const neighb2d& c4() Index: mln/core/dpoint2d.hh --- mln/core/dpoint2d.hh (revision 994) +++ mln/core/dpoint2d.hh (working copy) @@ -1,14 +1,31 @@ #ifndef MLN_CORE_DPOINT2D_HH # define MLN_CORE_DPOINT2D_HH +/*! \file mln/core/dpoint2d.hh + * + * \brief This file defines the mln::dpoint2d alias and its creation + * routine. + */ + # include <mln/core/dpoint.hh> namespace mln { + /*! \brief Type alias for a delta-point defined on the 2D square + * grid with integer coordinates. + */ typedef dpoint_<2,int> dpoint2d; + + /*! \brief Create a 2D delta-point. + * + * \param[in] row Index of row. + * \param[in] col Index of column. + * + * \return A dpoint2d. + */ dpoint2d mk_dpoint2d(int row, int col) { dpoint2d tmp; Index: mln/core/macros.hh --- mln/core/macros.hh (revision 994) +++ mln/core/macros.hh (working copy) @@ -5,11 +5,11 @@ * This file defines the set of milena macros. */ -/*! \def mln_point(T) +/*! \def mln_point */ -# define mln_point(T) typename T::point +# define mln_point typename T::point -/*! \def mln_dpoint(T) +/*! \def mln_dpoint */ # define mln_dpoint(T) typename T::dpoint Index: mln/core/box.hh --- mln/core/box.hh (revision 994) +++ mln/core/box.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_BOX_HH # define MLN_CORE_BOX_HH +/*! \file mln/core/box.hh + * + * \brief This file defines a generic box class. + */ + # include <mln/core/concept/box.hh> # include <mln/core/point.hh> @@ -13,33 +18,126 @@ template <typename P> struct box_bkd_piter_; + /*! \brief Generic box class. + * + * Parameter \c P is the corresponding type of point. + */ template <typename P> struct box_ : public Box< box_<P> > { + /*! \brief Psite associated type. + */ typedef P psite; + + /*! \brief Point associated type. + */ typedef P point; + /*! \brief Forward Piter associated type. + */ typedef box_fwd_piter_<P> fwd_piter; + + /*! \brief Backward Piter associated type. + */ typedef box_bkd_piter_<P> bkd_piter; + + /*! \brief Piter associated type. + */ typedef fwd_piter piter; - P pmin() const { return pmin_; } - P& pmin() { return pmin_; } + /*! \brief Minimum point. + */ + P pmin() const; + + /*! \brief Reference to the minimum point. + */ + P& pmin(); + + /*! \brief Maximum point. + */ + P pmax() const; + + /*! \brief Reference to the maximum point. + */ + P& pmax(); + + /*! \brief Constructor without argument. + */ + box_(); + + /*! \brief Constructor of a box going from \p pmin to \p pmax. + */ + box_(const point& pmin, const point& pmax); + + /*! \brief Test if \p p belongs to the box. + * + * \param[in] p A point site. + */ + bool has(const P& p) const; + + protected: + P pmin_, pmax_; + }; + + + /*! \brief Print a generic box \p b into the output stream \p ostr. + * + * \param[in,out] ostr An output stream. + * \param[in] b A generic box. + * + * \return The modified output stream \p ostr. + * + * \relates mln::box_ + */ + template <typename P> + std::ostream& operator<<(std::ostream& ostr, const box_<P>& b); + + +# ifndef MLN_INCLUDE_ONLY + + template <typename P> + P + box_<P>::pmin() const + { + return pmin_; + } + + template <typename P> + P& + box_<P>::pmin() + { + return pmin_; + } - P pmax() const { return pmax_; } - P& pmax() { return pmax_; } + template <typename P> + P + box_<P>::pmax() const + { + return pmax_; + } + + template <typename P> + P& + box_<P>::pmax() + { + return pmax_; + } - box_() + template <typename P> + box_<P>::box_() { } - box_(const point& pmin, const point& pmax) + template <typename P> + box_<P>::box_(const point& pmin, const point& pmax) : pmin_(pmin), pmax_(pmax) { } - bool has(const P& p) const + template <typename P> + bool + box_<P>::has(const P& p) const { for (unsigned i = 0; i < P::dim; ++i) if (p[i] < pmin_[i] or p[i] > pmax_[i]) @@ -47,17 +145,13 @@ return true; } - protected: - P pmin_, pmax_; - }; - - template <typename P> std::ostream& operator<<(std::ostream& ostr, const box_<P>& b) { return ostr << "[" << b.pmin() << ".." << b.pmax() << ']'; } +# endif // ! MLN_INCLUDE_ONLY } // end of namespace mln Index: mln/core/point.hh --- mln/core/point.hh (revision 994) +++ mln/core/point.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_POINT_HH # define MLN_CORE_POINT_HH +/*! \file mln/core/point.hh + * + * \brief This file defines a generic point class. + */ + # include <mln/core/concept/point.hh> # include <mln/core/internal/coord_impl.hh> @@ -12,19 +17,51 @@ template <unsigned n, typename C> struct dpoint_; + /*! \brief Generic point class. + * + * Parameters are \c n the dimension of the space and \c C the + * coordinate type in this space. + */ template <unsigned n, typename C> struct point_ : public Point< point_<n,C> >, public internal::mutable_coord_impl_< n, C, point_<n,C> > { + /*! \var dim + * \brief Dimension of the space. + * \invariant dim > 0 + */ enum { dim = n }; - typedef C coord; + + /*! \brief Dpoint associated type. + */ typedef dpoint_<n,C> dpoint; + /*! Coordinate associated type. + */ + typedef C coord; + + /*! \brief Read-only access to the \p i-th coordinate value. + * \param[in] i The coordinate index. + * \pre \p i < \c dim + */ C operator[](unsigned i) const; + + /*! \brief Read-write access to the \p i-th coordinate value. + * \param[in] i The coordinate index. + * \pre \p i < \c dim + */ C& operator[](unsigned i); + /*! \brief Constructor without argument. + */ point_(); + + /*! \brief Constructor; all coordinates are set to the value \p c. + */ point_(C c); + + /*! \brief Set all coordinates to the value \p c. + */ void set_all(C c); protected: Index: mln/core/rectangle2d.hh --- mln/core/rectangle2d.hh (revision 994) +++ mln/core/rectangle2d.hh (working copy) @@ -10,6 +10,7 @@ namespace mln { + // FIXME: doc. struct rectangle2d : public Window< rectangle2d >, public internal::set_of_<dpoint2d> { Index: mln/core/concept/image.hh --- mln/core/concept/image.hh (revision 994) +++ mln/core/concept/image.hh (working copy) @@ -1,12 +1,21 @@ #ifndef MLN_CORE_CONCEPT_IMAGE_HH # define MLN_CORE_CONCEPT_IMAGE_HH +/*! \file mln/core/concept/image.hh + * \brief This file defines the concept of mln::Image. + */ + # include <mln/core/concept/point_set.hh> namespace mln { + /*! \brief Base class for implementation of image classes. + * + * \see mln::doc::Image for a complete documentation of this class + * contents. + */ template <typename E> struct Image : public Object<E> { Index: mln/core/concept/genpoint.hh --- mln/core/concept/genpoint.hh (revision 994) +++ mln/core/concept/genpoint.hh (working copy) @@ -57,8 +57,8 @@ /*! \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. + * \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. @@ -73,10 +73,10 @@ /*! \brief Ordering "less than" comparison between a couple of generalized - * point \p lhs and \p rhs. + * points \p lhs and \p rhs. * - * @param[in] lhs A first generalized point. - * @param[in] rhs A second generalized point. + * \param[in] lhs A first generalized point. + * \param[in] rhs A second generalized point. * * This test is based on a lexicographical ordering over coordinates. * @@ -99,8 +99,8 @@ /*! \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. + * \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 @@ -112,7 +112,7 @@ * * \post The result, \p dp, is such as \p lhs = \p rhs + \p dp. * - * \return A delta-point. + * \return A delta-point (temporary object). * * \see mln::Dpoint * \relates mln::GenPoint @@ -124,13 +124,13 @@ /*! \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. + * \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). + * \return A point (temporary object). * * \see mln::Dpoint * \relates mln::GenPoint @@ -146,19 +146,12 @@ /*! \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. + * \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. + * \return The modified output stream \p ostr. * - * \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); @@ -208,7 +201,6 @@ return false; } - template <typename Pl, typename Pr> mln_dpoint(Pl) operator-(const GenPoint<Pl>& lhs, const GenPoint<Pr>& rhs) @@ -225,7 +217,6 @@ return tmp; } - template <typename P> mln_point(P) operator+(const GenPoint<P>& lhs, const mln_dpoint(P)& rhs) Index: mln/core/concept/object.hh --- mln/core/concept/object.hh (revision 994) +++ mln/core/concept/object.hh (working copy) @@ -11,6 +11,17 @@ # include <mln/core/macros.hh> +/*! \namespace mln + * \brief The namespace mln corresponds to the Milena (mini-Olena) project. + * + * The contents of mln mimics the contents of the olena project but + * in a simplified way. Some classes have the same name in both + * projects and roughly have the same behavior. + * + * \warning The Milena project is independent from the Olena + * project; the user has to choose between both the project she + * wants to work with. + */ namespace mln { Index: mln/core/concept/doc/image.hh --- mln/core/concept/doc/image.hh (revision 994) +++ mln/core/concept/doc/image.hh (working copy) @@ -1,5 +1,5 @@ /*! \file mln/core/concept/doc/image.hh - * This file documents the concept of mln::Image. + * \brief This file documents the concept of mln::Image. */ namespace mln @@ -8,26 +8,69 @@ namespace doc { - /*! Documentation class for mln::Image. + /*! \brief Documentation class for mln::Image. * \see mln::Image */ template <typename E> struct Image : public Object<E> { - // to be provided in concrete image classes: - + /*! \brief Value associated type. + * + * \invariant This type is neither qualified by const, nor by + * reference. + */ typedef void value; + + /*! \brief Type returned by the read pixel value operator. + */ typedef void rvalue; + + /*! \brief Type returned by the read-write pixel value operator. + */ typedef void lvalue; + /*! \brief Test if the image have been initialized. + */ bool has_data() const; - bool owns_(const psite& p) const; // default is like "has(p)" + /*! \brief Test if the image owns the poinst site \p p. + * + * \return True if accessing the image value at \p p is + * possible, that is, does not abort the execution. + */ + bool owns_(const psite& p) const; + + /*! \brief Give the definition domain of the image. + * + * \return A reference to the domain point set. + */ const pset& domain() const; + /*! \brief Read access to the image value located at \p p. + * + * \param[in] p A point site. + * + * \pre The image has to own the site \p p. + * + * \return The value at \p p. + */ rvalue operator()(const psite& p) const; + + /*! \brief Read-write access to the image value located at \p p. + * + * \param[in] p A point site. + * + * \pre The image has to own the site \p p. + * + * \return The value at \p p. + */ lvalue operator()(const psite& p); + + + /*! \brief Trait that gives the corresponding image type with + the value type changes to T. + */ template <typename T> struct change_value { @@ -35,17 +78,56 @@ }; - // provided by internal::image_base_: + /*! \brief Point set associated type. + * \invariant This type has to derive from mln::Point_Set. + */ typedef void pset; + + /*! \brief Point associated type. + * \invariant This type has to derive from mln::Point. + */ typedef void point; + + /*! \brief Psite associated type. + * \invariant This type has to derive from mln::Psite. + */ typedef void psite; + /*! \brief Piter associated type. + * \invariant This type has to derive from mln::Piter. + */ typedef void piter; + + /*! \brief Forward point iterator associated type. + * \invariant This type has to derive from mln::Piter. + */ typedef void fwd_piter; + + /*! \brief Backward point iterator associated type. + * \invariant This type has to derive from mln::Piter. + */ typedef void bkd_piter; + /*! \brief Test if \p p belongs to the image domain. + * + * \param[in] p A point site. + * + * \return True if \p p belongs to the image domain. + * + * \invariant has(p) is true => owns_(p) is also true. + */ bool has(const psite& p) const; + + /*! \brief Give a bounding box of the image domain. + * + * This bounding box may be larger than the smallest bounding + * box (the optimal one). Practically an image type is not + * obliged to update its bounding box so that it is always + * optimal. + * + * \return A bounding box of the image domain. + */ const box_<point>& bbox() const; }; Index: mln/core/concept/doc/genpoint.hh --- mln/core/concept/doc/genpoint.hh (revision 994) +++ mln/core/concept/doc/genpoint.hh (working copy) @@ -9,6 +9,7 @@ { /*! \brief Documentation class for mln::GenPoint. + * * \see mln::GenPoint */ template <typename E> @@ -50,7 +51,7 @@ /*! \brief Read-only access to the \p i-th coordinate value. * - * @param[in] i The coordinate index. + * \param[in] i The coordinate index. * * \pre \p i < \c dim * Index: mln/core/concept/doc/point_set.hh --- mln/core/concept/doc/point_set.hh (revision 994) +++ mln/core/concept/doc/point_set.hh (working copy) @@ -9,6 +9,7 @@ { /*! \brief Documentation class for mln::Point_Set. + * * \see mln::Point_Set */ template <typename E> @@ -34,9 +35,9 @@ */ typedef void bkd_piter; - /*! \brief Test if the \p p belongs to this point set. + /*! \brief Test if \p p belongs to this point set. * - * @param[in] p A point site. + * \param[in] p A point site. * \return True if \p p is an element of the point set. */ bool has(const psite& p) const; Index: mln/core/concept/doc/object.hh --- mln/core/concept/doc/object.hh (revision 994) +++ mln/core/concept/doc/object.hh (working copy) @@ -4,6 +4,7 @@ namespace mln { + /*! \namespace mln::doc * \brief The namespace mln::doc is only for documentation purpose. * Index: mln/core/concept/doc/neighborhood.hh --- mln/core/concept/doc/neighborhood.hh (revision 994) +++ mln/core/concept/doc/neighborhood.hh (working copy) @@ -1,5 +1,5 @@ /*! \file mln/core/concept/doc/neighborhood.hh - * This file documents the concept of mln::Neighborhood. + * \brief This file documents the concept of mln::Neighborhood. */ namespace mln @@ -8,14 +8,26 @@ namespace doc { - /*! Documentation class for mln::Neighborhood. + /*! \brief Documentation class for mln::Neighborhood. + * * \see mln::Neighborhood */ template <typename E> struct Neighborhood : public Object<E> { + /*! \brief Piter type associated to this neighborhood to browse + * neighbors. + */ typedef void niter; + + /*! \brief Piter type associated to this neighborhood to browse + * neighbors in a forward way. + */ typedef void fwd_niter; + + /*! \brief Piter type associated to this neighborhood to browse + * neighbors in a backward way. + */ typedef void bkd_niter; }; Index: mln/core/concept/doc/window.hh --- mln/core/concept/doc/window.hh (revision 994) +++ mln/core/concept/doc/window.hh (working copy) @@ -9,6 +9,10 @@ { /*! \brief Documentation class for mln::Window. + * + * A window is the definition of a set of points located around a + * central point. + * * \see mln::Window */ template <typename E> Index: mln/core/concept/doc/box.hh --- mln/core/concept/doc/box.hh (revision 994) +++ mln/core/concept/doc/box.hh (working copy) @@ -1,5 +1,5 @@ /*! \file mln/core/concept/doc/box.hh - * This file documents the concept of mln::Box. + * \brief This file documents the concept of mln::Box. */ namespace mln @@ -8,29 +8,29 @@ namespace doc { - /*! Documentation class for mln::Box. + /*! \brief Documentation class for mln::Box. * \see mln::Box */ template <typename E> struct Box : public Point_Set<E> { - /*! \fn const point& pmin() const + /*! \brief Return the box "minimum" point. * - * Return the minimum point w.r.t. the ordering between points. - * - * In 2D this minimum is the top left point of the box. + * Return the "minimum" point w.r.t. the ordering between points. + * For instance, with mln::box2d, 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. + /*! \brief Return the box "maximum" point. * - * In 2D this maximum is the bottom right point of the box. + * Return the "maximum" point w.r.t. the ordering between points. + * For instance, with mln::box2d, this maximum is the bottom + * right point of the box. */ const point& pmax() const; - /*! \fn const E& bbox() const + /*! \brief Return the bounding box of this point set. * * Return the bounding box of this point set, so that is itself. * This method is declared by the mln::Point_Set concept. @@ -39,7 +39,7 @@ */ const E& bbox() const; - /*! \fn std::size_t npoints() const + /*! \brief Return the number of points of this box. * * Return the number of points of this box. This method is * declared by the mln::Point_Set concept. Index: mln/core/concept/doc/iterator.hh --- mln/core/concept/doc/iterator.hh (revision 994) +++ mln/core/concept/doc/iterator.hh (working copy) @@ -1,5 +1,5 @@ /*! \file mln/core/concept/doc/iterator.hh - * This file documents the concept of mln::Iterator. + * \brief This file documents the concept of mln::Iterator. */ @@ -9,27 +9,33 @@ namespace doc { - /*! Documentation class for mln::Iterator. + /*! \brief 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 + /*! \brief Returns true if the iterator is valid, that is, designates * an element. */ bool is_valid() const; - /*! Invalidate the iterator. + /*! \brief Invalidate the iterator. */ void invalidate(); - /*! Start an iteration, that is, make the iterator designate the - * first element if it exists. + /*! \brief Start an iteration. + * + * Make the iterator designate the first element if it exists. + * If this first element does not exist, the iterator is not + * valid. */ void start(); - /*! Make the iterator designate the next element. + /*! \brief Go to the next element. + * + * Make the iterator jump from the current element to the next + * one. The current element is thus updated. */ void next_(); Index: mln/core/concept/doc/dpoint.hh --- mln/core/concept/doc/dpoint.hh (revision 994) +++ mln/core/concept/doc/dpoint.hh (working copy) @@ -1,5 +1,5 @@ /*! \file mln/core/concept/doc/dpoint.hh - * This file documents the concept of mln::Dpoint. + * \brief This file documents the concept of mln::Dpoint. */ namespace mln @@ -8,15 +8,40 @@ namespace doc { - /*! Documentation class for mln::Dpoint. + /*! \brief Documentation class for mln::Dpoint. * \see mln::Dpoint */ template <typename E> struct Dpoint : public Object<E> { - typedef point; - typedef coord; + /*! \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; + + /*! \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/neighborhood.hh --- mln/core/concept/neighborhood.hh (revision 994) +++ mln/core/concept/neighborhood.hh (working copy) @@ -1,12 +1,21 @@ #ifndef MLN_CORE_CONCEPT_NEIGHBORHOOD_HH # define MLN_CORE_CONCEPT_NEIGHBORHOOD_HH +/*! \file mln/core/concept/neighborhood.hh + * \brief This file defines the concept of mln::Neighborhood. + */ + # include <mln/core/concept/object.hh> namespace mln { + /*! \brief Base class for implementation classes that are neighborhoods. + * + * \see mln::doc::Neighborhood for a complete documentation of this + * class contents. + */ template <typename E> struct Neighborhood : public Object<E> { Index: mln/core/concept/box.hh --- mln/core/concept/box.hh (revision 994) +++ mln/core/concept/box.hh (working copy) @@ -27,8 +27,23 @@ const point& pmax() const; */ - const E& bbox() const; //! final; \see mln::doc::Box::bbox - std::size_t npoints() const; //! final; \see mln::doc::Box::npoints + /*! \brief Return the bounding box of this point set. + * + * 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; + + /*! \brief Return the number of points of this box. + * + * 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; protected: Box(); Index: mln/core/concept/point.hh --- mln/core/concept/point.hh (revision 994) +++ mln/core/concept/point.hh (working copy) @@ -13,7 +13,10 @@ /*! \brief Base class for implementation of point classes. * - * A point is a vector in a space. + * A point is an element of a space. + * + * For instance, mln::point2d is the type of elements defined on the + * discrete square grid of the 2D plane. */ template <typename P> struct Point : public Psite<P> @@ -33,8 +36,8 @@ /*! \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. + * \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. @@ -50,8 +53,8 @@ /*! \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. + * \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. Index: mln/core/concept/dpoint.hh --- mln/core/concept/dpoint.hh (revision 994) +++ mln/core/concept/dpoint.hh (working copy) @@ -1,6 +1,10 @@ #ifndef MLN_CORE_CONCEPT_DPOINT_HH # define MLN_CORE_CONCEPT_DPOINT_HH +/*! \file mln/core/concept/dpoint.hh + * \brief This file defines the concept of mln::Dpoint. + */ + # include <mln/core/concept/object.hh> @@ -8,6 +12,16 @@ { + /*! \brief Base class for implementation of delta-point classes. + * + * A delta-point is a vector defined by a couple of points. + * + * Given two points, A and B, the vector AB is mapped into the + * delta-point D = AB. Practically one can write: D = B - A. + * + * \see mln::doc::Dpoint for a complete documentation of this class + * contents. + */ template <typename E> struct Dpoint : public Object<E> { @@ -23,15 +37,65 @@ }; + /*! \brief Give the negate of the delta-point \p rhs. + * + * \param[in] rhs The targeted delta-point. + * + * \invariant For all delta-point dp, we have: -(-dp) = dp. + * + * \return A delta-point (temporary object). + * + * \relates mln::Dpoint + */ template <typename D> - D operator-(const Dpoint<D>& dp); + D operator-(const Dpoint<D>& rhs); + + /*! \brief Equality comparison between a couple of delta-point \p lhs + * and \p rhs. + * + * \param[in] lhs A first delta-point. + * \param[in] rhs A second delta-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 delta-points have the same coordinates, + * otherwise false. + * + * \relates mln::Dpoint + */ template <typename Dl, typename Dr> bool operator=(const Dpoint<Dl>& lhs, const Dpoint<Dr>& rhs); + + /*! \brief Ordering "less than" comparison between a couple of + * delta-points \p lhs and \p rhs. + * + * \param[in] lhs A first delta-point. + * \param[in] rhs A second delta-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 delta-points have the same coordinates, + * otherwise false. + * + * \relates mln::Dpoint + */ template <typename Dl, typename Dr> bool operator<(const Dpoint<Dl>& lhs, const Dpoint<Dr>& rhs); + + /*! \brief Print a delta-point \p p into the output stream \p ostr. + * + * \param[in,out] ostr An output stream. + * \param[in] dp A delta-point. + * + * \return The modified output stream \p ostr. + * + * \relates mln::Dpoint + */ template <typename D> std::ostream& operator<<(std::ostream& ostr, const Dpoint<D>& dp); @@ -50,11 +114,11 @@ } template <typename D> - D operator-(const Dpoint<D>& dp) + D operator-(const Dpoint<D>& rhs) { D tmp; for (unsigned i = 0; i < D::dim; ++i) - tmp[i] = - exact(dp)[i]; + tmp[i] = - exact(rhs)[i]; return tmp; } Index: mln/core/window2d.hh --- mln/core/window2d.hh (revision 994) +++ mln/core/window2d.hh (working copy) @@ -1,6 +1,12 @@ #ifndef MLN_CORE_WINDOW2D_HH # define MLN_CORE_WINDOW2D_HH +/*! \file mln/core/window2d.hh + * + * \brief This file defines the mln::window2d alias and its creation + * routine. + */ + # include <cmath> # include <mln/core/window.hh> # include <mln/core/dpoint2d.hh> @@ -9,8 +15,20 @@ namespace mln { + /*! \brief Type alias for a window with arbitrary shape, defined on + * the 2D square grid with integer coordinates. + */ typedef window_<dpoint2d> window2d; + + /*! \brief Create a 2D window with arbitrary shape. + * + * \param[in] values Array of Booleans. + * + * \pre The array size, \c M, has to be a square of an odd integer. + * + * \return A window2d. + */ template <unsigned M> window2d mk_window2d(const bool (&values)[M]); Index: mln/core/dpoint.hh --- mln/core/dpoint.hh (revision 994) +++ mln/core/dpoint.hh (working copy) @@ -1,6 +1,11 @@ #ifndef MLN_CORE_DPOINT_HH # define MLN_CORE_DPOINT_HH +/*! \file mln/core/dpoint.hh + * + * \brief This file defines a generic delta-point class. + */ + # include <mln/core/concept/dpoint.hh> # include <mln/core/internal/coord_impl.hh> @@ -12,19 +17,51 @@ template <unsigned n, typename C> struct point_; + /*! \brief Generic delta-point class. + * + * Parameters are \c n the dimension of the space and \c C the + * coordinate type in this space. + */ template <unsigned n, typename C> struct dpoint_ : public Dpoint< dpoint_<n,C> >, public internal::mutable_coord_impl_< n, C, dpoint_<n,C> > { + /*! \var dim + * \brief Dimension of the space. + * \invariant dim > 0 + */ enum { dim = n }; - typedef C coord; + + /*! \brief Point associated type. + */ typedef point_<n,C> point; + /*! Coordinate associated type. + */ + typedef C coord; + + /*! \brief Read-only access to the \p i-th coordinate value. + * \param[in] i The coordinate index. + * \pre \p i < \c dim + */ C operator[](unsigned i) const; + + /*! \brief Read-write access to the \p i-th coordinate value. + * \param[in] i The coordinate index. + * \pre \p i < \c dim + */ C& operator[](unsigned i); + /*! \brief Constructor without argument. + */ dpoint_(); + + /*! \brief Constructor; all coordinates are set to the value \p c. + */ dpoint_(C c); + + /*! \brief Set all coordinates to the value \p c. + */ void set_all(C c); protected: Index: mln/core/ops.hh --- mln/core/ops.hh (revision 994) +++ mln/core/ops.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_OPS_HH /*! \file mln/core/ops.hh - * Default definitions of some operators. + * \brief Definitions of some operators. */ # include <mln/core/concept/object.hh> @@ -12,7 +12,9 @@ namespace mln { - /*! The "not equal to" operator is here defined for every milena + /*! \brief General definition of the "not equal to" operator. + * + * 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)". * @@ -22,7 +24,10 @@ 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 + + /*! \brief General definition of the "greater than" operator. + * + * 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". * @@ -32,7 +37,11 @@ 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 + + /*! \brief General definition of the "greater than or equal to" + * operator. + * + * 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". * @@ -42,7 +51,11 @@ 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 + + /*! \brief Default definition of the "less than or equal to" + * operator. + * + * 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)". * Index: mln/core/exact.hh --- mln/core/exact.hh (revision 994) +++ mln/core/exact.hh (working copy) @@ -2,7 +2,7 @@ # define MLN_CORE_EXACT_HH /*! \file mln/core/exact.hh - * This file defines the mln::exact downcast routines. + * \brief This file defines the mln::exact downcast routines. */ # include <mln/core/concept/object.hh> @@ -11,12 +11,16 @@ namespace mln { - /*! The mln::exact routine downcasts an object towards its exact - * type. + /*! \brief Exact cast routine for mln objects. * - * The only argument is an mln::Object. The return follows the - * nature of the argument (either a pointer or a reference, const or - * not). + * This set of routines can be used to downcast an object towards + * its exact type. The only argument, respectively \p ptr or \p + * ref, should be an mln::Object. + * + * \c The parameter E is the exact type of the object. + * + * \return The return follows the nature of the argument (either a + * pointer or a reference, const or not). */ /// \{ @@ -36,11 +40,17 @@ - /*! The mln::force_exact is a violent cast routine. + /*! \brief Violent exact cast routine. + * + * This cast is an alternative to the mln::exact cast. It is used + * for objects than do not derive from mln::Object. * * It preserves the nature (pointer or reference, const or mutable) * of its argument. The parameter \a E should not have qualifiers. * + * \warning Prefer not to use this cast! + * + * \see mln::exact * \todo Move into mln::internal. */ /// \{ Index: mln/core/box2d.hh --- mln/core/box2d.hh (revision 994) +++ mln/core/box2d.hh (working copy) @@ -1,6 +1,12 @@ #ifndef MLN_CORE_BOX2D_HH # define MLN_CORE_BOX2D_HH +/*! \file mln/core/box2d.hh + * + * \brief This file defines the mln::box2d alias and construction + * routines. + */ + # include <mln/core/box.hh> # include <mln/core/point2d.hh> @@ -8,18 +14,51 @@ namespace mln { + /*! \brief Type alias for a box defined on the 2D square grid with + * integer coordinates. + */ typedef box_<point2d> box2d; + + /*! \brief Create a 2D box. + * + * \param[in] nrows Number of rows. + * \param[in] ncols Number of columns. + * + * \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); box2d tmp(mk_point2d(0, 0), mk_point2d(nrows - 1, ncols - 1)); return tmp; } + + /*! \brief Create a 2D box. + * + * \overload + * + * \param[in] min_row Index of the top most row. + * \param[in] max_row Index of the botton most row. + * \param[in] min_col Index of the left most column. + * \param[in] max_col Index of the right most column. + * + * \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); 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 994) +++ mln/core/point2d.hh (working copy) @@ -1,14 +1,31 @@ #ifndef MLN_CORE_POINT2D_HH # define MLN_CORE_POINT2D_HH +/*! \file mln/core/point2d.hh + * + * \brief This file defines the mln::point2d alias and its creation + * routine. + */ + # include <mln/core/point.hh> namespace mln { + /*! \brief Type alias for a point defined on the 2D square grid with + * integer coordinates. + */ typedef point_<2,int> point2d; + + /*! \brief Create a 2D point. + * + * \param[in] row Index of row. + * \param[in] col Index of column. + * + * \return A point2d. + */ point2d mk_point2d(int row, int col) { point2d tmp;