Commit 5bd6f093 authored by Thierry Geraud's avatar Thierry Geraud
Browse files

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.


git-svn-id: https://svn.lrde.epita.fr/svn/oln/trunk@993 4aad255d-cdde-0310-9447-f3009e2ae8c0
parent 7a6b43eb
2007-07-03 Thierry Geraud <thierry.geraud@lrde.epita.fr>
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.
2007-07-02 Roland Levillain <roland@lrde.epita.fr>
Move Milena source files to mln/.
......
......@@ -1007,13 +1007,13 @@ ENABLE_PREPROCESSING = YES
# 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 @@ PREDEFINED =
# 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
......
#ifndef MLN_MLC_EQUAL_HH
# define MLN_MLC_EQUAL_HH
#ifndef MLC_EQUAL_HH
# define MLC_EQUAL_HH
namespace mln
......@@ -25,4 +25,4 @@ namespace mln
} // end of namespace mln
#endif // ! MLN_MLC_EQUAL_HH
#endif // ! MLC_EQUAL_HH
#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
#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 @@ namespace mln
{
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 @@ namespace mln
} // end of namespace mln
#endif // ! MLN_MLC_SAME_POINT_HH
#endif // ! MLC_SAME_POINT_HH
#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 @@ namespace mln
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();
......
/*! \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
/*! \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
/*! \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 mln
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;
};
......
/*! \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
/*! \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
/*! \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
/*! \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
/*! \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
/*! \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
/*! \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
......@@ -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.
*