[Olena-patches] 999: Add extra documentation to milena.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Thierry Geraud &lt;thierry.geraud(a)lrde.epita.fr&gt; Add extra documentation to milena. * mln/debug/all.hh, * mln/level/all.hh, * mln/value/all.hh: New facade files. * mln/debug/println.hh, * mln/level/fill.hh, * mln/level/compare.hh, * mln/level/paste.hh, * mln/value/props.hh: Add documentation. debug/all.hh | 50 ++++++++++++++++++++++++++++++++++++++++ debug/println.hh | 10 ++++---- level/all.hh | 53 ++++++++++++++++++++++++++++++++++++++++++ level/compare.hh | 32 +++++++++++++++++++++++++ level/fill.hh | 68 +++++++++++++++++++++++++++++++++++++++++++++++-------- level/paste.hh | 22 +++++++++++++++++ value/all.hh | 51 +++++++++++++++++++++++++++++++++++++++++ value/props.hh | 16 ++++++++++++ 8 files changed, 289 insertions(+), 13 deletions(-) Index: mln/debug/println.hh --- mln/debug/println.hh (revision 998) +++ mln/debug/println.hh (working copy) @@ -28,6 +28,11 @@ #ifndef MLN_DEBUG_PRINTLN_HH # define MLN_DEBUG_PRINTLN_HH +/*! \file mln/debug/println.hh + * + * \brief Print an image on the standard output. + */ + # include <mln/core/concept/image.hh> # include <mln/core/concept/window.hh> # include <mln/core/box2d.hh> @@ -39,13 +44,10 @@ namespace debug { + /// Print the image \p input on the standard output. template <typename I> void println(const Image<I>& input); - template <typename I, typename W> - void println(const Image<I>& input_, - const Window<W>& win_); - # ifndef MLN_INCLUDE_ONLY Index: mln/debug/all.hh --- mln/debug/all.hh (revision 0) +++ mln/debug/all.hh (revision 0) @@ -0,0 +1,50 @@ +// Copyright (C) 2007 EPITA Research and Development Laboratory +// +// This file is part of the Olena Library. This library is free +// software; you can redistribute it and/or modify it under the terms +// of the GNU General Public License version 2 as published by the +// Free Software Foundation. +// +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this library; see the file COPYING. If not, write to +// the Free Software Foundation, 51 Franklin Street, Fifth Floor, +// Boston, MA 02111-1307, USA. +// +// As a special exception, you may use this file as part of a free +// software library without restriction. Specifically, if other files +// instantiate templates or use macros or inline functions from this +// file, or you compile this file and link it with other files to +// produce an executable, this file does not by itself cause the +// resulting executable to be covered by the GNU General Public +// License. This exception does not however invalidate any other +// reasons why the executable file might be covered by the GNU General +// Public License. + +#ifndef MLN_DEBUG_ALL_HH +# define MLN_DEBUG_ALL_HH + +/*! \file mln/debug/all.hh + * + * \brief File that includes all debug-related routines. + */ + + +namespace mln +{ + + /*! Namespace of routines that help to debug. + */ + namespace debug {} + +} + + +# include <mln/debug/println.hh> + + +#endif // ! MLN_DEBUG_ALL_HH Index: mln/level/fill.hh --- mln/level/fill.hh (revision 998) +++ mln/level/fill.hh (working copy) @@ -28,6 +28,11 @@ #ifndef MLN_LEVEL_FILL_HH # define MLN_LEVEL_FILL_HH +/*! \file mln/level/fill.hh + * + * \brief Fill an image, that is, set pixel values. + */ + # include <mln/core/concept/image.hh> @@ -37,23 +42,68 @@ namespace level { + /*! Fill the whole image \p ima with the single value \p v. + * + * \param[in,out] ima The image to be filled. + * \param[in] v The value to assign to all pixels. + * + * \pre \p ima has to be initialized. + */ + template <typename I> + void fill(Image<I>& ima, + const mln_value(I)& v); + + + /*! Fill the image \p ima by applying the function \p f. + * + * \param[in,out] ima The image to be filled. + * \param[in] f The function that defines the value of every pixel. + * + * The signature of \p f has to be: + * " value f(const point& p) " + * + * \pre \p ima has to be initialized. + */ template <typename I> - void fill(Image<I>& ima_, - const mln_value(I)& value); - - template <typename I> - void fill(Image<I>& ima_, + void fill(Image<I>& ima, mln_value(I) (*f)(const mln_point(I)& p)); - template <typename I> - void fill(Image<I>& ima_, - const mln_value(I) array[]); + /*! Fill the image \p ima with the values given by the array \p arr. + * + * \param[in,out] ima The image to be filled. + * \param[in] arr The array of values. + * + * \warning The size of the array has to be larger than the number + * of image points, otherwise the program crashes. + * + * \pre \p ima has to be initialized. + * + * \todo Add as parameter the array size, then add a test. + */ + template <typename I> + void fill(Image<I>& ima, + const mln_value(I) arr[]); + + + /*! Fill the image \p ima with the values of the image \p data. + * + * \param[in,out] ima The image to be filled. + * \param[in] data The image. + * + * \warning The definition domain of \p ima has to be included in + * the one of \p data. + * + * \pre \p ima has to be initialized. + * + * \todo Test domain inclusion. + */ template <typename I, typename J> - void fill(Image<I>& ima_, + void fill(Image<I>& ima, const Image<J>& data); + # ifndef MLN_INCLUDE_ONLY template <typename I> Index: mln/level/compare.hh --- mln/level/compare.hh (revision 998) +++ mln/level/compare.hh (working copy) @@ -28,22 +28,54 @@ #ifndef MLN_LEVEL_COMPARE_HH # define MLN_LEVEL_COMPARE_HH +/*! \file mln/level/compare.hh + * + * \brief Comparison operators between the pixel values of images. + */ + # include <mln/core/concept/image.hh> namespace mln { + /*! Point-wise test if the pixel values of \p lhs are equal to the + * pixel values of \p rhs. + * + * \param[in] lhs A first image. + * \param[in] rhs A second image. + * + * \todo Test domain equality. + */ template <typename L, typename R> bool operator = (const Image<L>& lhs, const Image<R>& rhs); + + /*! Point-wise test if the pixel values of \p lhs are point-wise + * less than the pixel values of \p rhs. + * + * \param[in] lhs A first image. + * \param[in] rhs A second image. + * + * \todo Test domain equality. + */ template <typename L, typename R> bool operator < (const Image<L>& lhs, const Image<R>& rhs); + + /*! Point-wise test if the pixel values of \p lhs are point-wise + * less than or equal to the pixel values of \p rhs. + * + * \param[in] lhs A first image. + * \param[in] rhs A second image. + * + * \todo Test domain equality. + */ template <typename L, typename R> // required! bool operator <= (const Image<L>& lhs, const Image<R>& rhs); + # ifndef MLN_INCLUDE_ONLY template <typename L, typename R> Index: mln/level/all.hh --- mln/level/all.hh (revision 0) +++ mln/level/all.hh (revision 0) @@ -0,0 +1,53 @@ +// Copyright (C) 2007 EPITA Research and Development Laboratory +// +// This file is part of the Olena Library. This library is free +// software; you can redistribute it and/or modify it under the terms +// of the GNU General Public License version 2 as published by the +// Free Software Foundation. +// +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this library; see the file COPYING. If not, write to +// the Free Software Foundation, 51 Franklin Street, Fifth Floor, +// Boston, MA 02111-1307, USA. +// +// As a special exception, you may use this file as part of a free +// software library without restriction. Specifically, if other files +// instantiate templates or use macros or inline functions from this +// file, or you compile this file and link it with other files to +// produce an executable, this file does not by itself cause the +// resulting executable to be covered by the GNU General Public +// License. This exception does not however invalidate any other +// reasons why the executable file might be covered by the GNU General +// Public License. + +#ifndef MLN_LEVEL_ALL_HH +# define MLN_LEVEL_ALL_HH + +/*! \file mln/level/all.hh + * + * \brief File that includes all level-related routines. + */ + + +namespace mln +{ + + /*! Namespace of image processing routines related to pixel levels. + */ + namespace level {} + +} + + +# include <mln/level/fill.hh> +# include <mln/level/compare.hh> +# include <mln/level/paste.hh> + + + +#endif // ! MLN_LEVEL_ALL_HH Index: mln/level/paste.hh --- mln/level/paste.hh (revision 998) +++ mln/level/paste.hh (working copy) @@ -28,6 +28,11 @@ #ifndef MLN_LEVEL_PASTE_HH # define MLN_LEVEL_PASTE_HH +/*! \file mln/level/paste.hh + * + * \brief Paste the contents of an image into another one. + */ + # include <mln/core/concept/image.hh> @@ -37,6 +42,23 @@ namespace level { + /*! Paste the contents of image \p data into the image \p + * destination. + * + * \param[in] data The input image providing pixels values. + * \param[in,out] destination The image in which values are + * assigned. + * + * This routine runs: \n + * for all p of \p data, \p destination(p) = \p data(p). + * + * \warning The definition domain of \p data has to be included + * in the one of \p destination. + * + * \pre Both images have to be initialized. + * + * \todo Test domain inclusion. + */ template <typename I, typename J> void paste(const Image<I>& data, Image<J>& destination); Index: mln/value/props.hh --- mln/value/props.hh (revision 998) +++ mln/value/props.hh (working copy) @@ -28,23 +28,39 @@ #ifndef MLN_VALUE_PROPS_HH # define MLN_VALUE_PROPS_HH +/*! \file mln/value/props.hh + * + * \brief Define properties of value types. + */ + # include <climits> # include <cfloat> + +/// Get the minimum value of type \c T. # define mln_min(T) mln::value::props<T>::min() + + +/// Get the maximum value of type \c T. # define mln_max(T) mln::value::props<T>::max() + namespace mln { namespace value { + /*! Class that defines the properties of the value type \c T. + */ template <typename T> struct props { + /// Minimum value for type \c T. static T min(); + + /// Maximum value for type \c T. static T max(); }; Index: mln/value/all.hh --- mln/value/all.hh (revision 0) +++ mln/value/all.hh (revision 0) @@ -0,0 +1,51 @@ +// Copyright (C) 2007 EPITA Research and Development Laboratory +// +// This file is part of the Olena Library. This library is free +// software; you can redistribute it and/or modify it under the terms +// of the GNU General Public License version 2 as published by the +// Free Software Foundation. +// +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this library; see the file COPYING. If not, write to +// the Free Software Foundation, 51 Franklin Street, Fifth Floor, +// Boston, MA 02111-1307, USA. +// +// As a special exception, you may use this file as part of a free +// software library without restriction. Specifically, if other files +// instantiate templates or use macros or inline functions from this +// file, or you compile this file and link it with other files to +// produce an executable, this file does not by itself cause the +// resulting executable to be covered by the GNU General Public +// License. This exception does not however invalidate any other +// reasons why the executable file might be covered by the GNU General +// Public License. + +#ifndef MLN_VALUE_ALL_HH +# define MLN_VALUE_ALL_HH + +/*! \file mln/value/all.hh + * + * \brief File that includes all "value types"-related materials. + */ + + +namespace mln +{ + + /*! Namespace of materials related to ixel value types. + */ + namespace value {} + +} + + +# include <mln/value/props.hh> + + + +#endif // ! MLN_VALUE_ALL_HH