[Olena-patches] 1650: Documentation and aesthetic changes.

https://svn.lrde.epita.fr/svn/oln/trunk/milena Index: ChangeLog from Roland Levillain &lt;roland(a)lrde.epita.fr&gt; Documentation and aesthetic changes. * mln/core/trait/qlf_value.hh, * mln/core/internal/image_value_morpher.hh, * mln/fun/c.hh, * mln/metal/is_a.hh: More Doxygen documentation. * mln/level/transform.hh, * mln/core/tr_image.hh, * mln/value/ops.hh: Wrap long lines. core/internal/image_morpher.hh | 4 ++++ core/internal/image_value_morpher.hh | 5 ++++- core/tr_image.hh | 16 ++++++++++++---- core/trait/qlf_value.hh | 4 +++- fun/c.hh | 3 ++- fun/v2v/norm.hh | 2 ++ level/stretch.hh | 1 + level/transform.hh | 9 ++++++--- metal/is_a.hh | 8 ++++++++ norm/l1.hh | 2 ++ norm/l2.hh | 3 +++ value/ops.hh | 7 ++++--- 12 files changed, 51 insertions(+), 13 deletions(-) Index: mln/core/internal/image_value_morpher.hh --- mln/core/internal/image_value_morpher.hh (revision 1649) +++ mln/core/internal/image_value_morpher.hh (working copy) @@ -1,4 +1,4 @@ -// Copyright (C) 2007 EPITA Research and Development Laboratory +// Copyright (C) 2007, 2008 EPITA Research and Development Laboratory (LRDE) // // This file is part of the Olena Library. This library is free // software; you can redistribute it and/or modify it under the terms @@ -31,6 +31,9 @@ /*! \file mln/core/internal/image_value_morpher.hh * * \brief Definition of a base class for image morphers w.r.t. value. + * + * A value morpher alters methods dealing with values (even if the + * actual values are not changed), but leaves the domain untouched. */ # include <mln/core/internal/image_morpher.hh> Index: mln/core/internal/image_morpher.hh --- mln/core/internal/image_morpher.hh (revision 1649) +++ mln/core/internal/image_morpher.hh (working copy) @@ -55,9 +55,13 @@ typedef I delegatee; + /* FIXME: Change the interface of this method: return a reference + instead of a pointer. */ /// Return the delegatee_ pointer; default code. mlc_const(I)* delegatee_() const; + /* FIXME: Change the interface of this method: return a reference + instead of a pointer. */ /// Return the delegatee_ pointer (non-const version); default code. I* delegatee_(); Index: mln/core/tr_image.hh --- mln/core/tr_image.hh (revision 1649) +++ mln/core/tr_image.hh (working copy) @@ -30,8 +30,8 @@ /*! \file mln/core/tr_image.hh * - * \brief Definition of a morpher that makes an image become - * transformed by a given transformation. + * \brief Definition of the morpher mln::tr_image presenting an image + * through a (bijective) transformation. * */ @@ -68,11 +68,13 @@ * */ template <typename T, typename I> - struct tr_image : public mln::internal::image_identity_< I, mln_pset(I), tr_image<T,I> > + struct tr_image : + public mln::internal::image_identity_< I, mln_pset(I), tr_image<T,I> > { /// Super type. - typedef mln::internal::image_identity_< I, mln_pset(I), tr_image<T,I> > super_; + typedef + mln::internal::image_identity_< I, mln_pset(I), tr_image<T,I> > super_; /// Point_Site associated type. typedef mln_psite(I) psite; @@ -96,6 +98,12 @@ /// Constructors. tr_image(I& ima, T& tr); + /* FIXME: What's the purpose of this ctor? AFAIK, morphers + objects (and images in general) cannot have their structure / + core data altered after they're built. Here, there's a + (partial) exception: this morpher provides set_tr(), but has no + set_ima(). I (Roland) don't see the point in keeping this ctor + if we do not provide set_ima(). */ tr_image(); Index: mln/core/trait/qlf_value.hh --- mln/core/trait/qlf_value.hh (revision 1649) +++ mln/core/trait/qlf_value.hh (working copy) @@ -1,4 +1,4 @@ -// Copyright (C) 2007 EPITA Research and Development Laboratory +// Copyright (C) 2007, 2008 EPITA Research and Development Laboratory (LRDE) // // This file is part of the Olena Library. This library is free // software; you can redistribute it and/or modify it under the terms @@ -31,6 +31,8 @@ /*! \file mln/core/trait/qlf_value.hh * * \brief Definition of the qlf_value image trait. + * + * qlf stands for ``qualified''. */ # include <mln/core/macros.hh> Index: mln/metal/is_a.hh --- mln/metal/is_a.hh (revision 1649) +++ mln/metal/is_a.hh (working copy) @@ -36,6 +36,14 @@ # include <mln/metal/bool.hh> +/// \brief Expand to a "metalic" boolean expression stating whether \a +/// T is a subclass of \a U or not. +/// +/// In the current implementation, \a U must be template class with +/// exactly one, non template parameter. +/// +/// This macro is the recommended user interface of the "is_a" +/// facility. # define mlc_is_a(T, U) mln::metal::is_a< T, U > Index: mln/level/transform.hh --- mln/level/transform.hh (revision 1649) +++ mln/level/transform.hh (working copy) @@ -65,7 +65,8 @@ * \pre \p output.domain >= \p input.domain */ template <typename I, typename F, typename O> - void transform(const Image<I>& input, const Function_v2v<F>& f, Image<O>& output); + void transform(const Image<I>& input, const Function_v2v<F>& f, + Image<O>& output); template <typename I, typename F> @@ -83,7 +84,8 @@ template <typename I, typename F, typename O> inline - void transform_(const Image<I>& input_, const Function_v2v<F>& f_, Image<O>& output_) + void transform_(const Image<I>& input_, const Function_v2v<F>& f_, + Image<O>& output_) { trace::entering("level::impl::generic::transform"); @@ -107,7 +109,8 @@ template <typename I, typename F, typename O> inline - void transform(const Image<I>& input, const Function_v2v<F>& f, Image<O>& output) + void transform(const Image<I>& input, const Function_v2v<F>& f, + Image<O>& output) { trace::entering("level::transform"); Index: mln/level/stretch.hh --- mln/level/stretch.hh (revision 1649) +++ mln/level/stretch.hh (working copy) @@ -62,6 +62,7 @@ namespace impl { + // FIXME: The first argument seems to have no effect. template <unsigned n, typename I, typename O> inline void stretch(value::int_u<n>, Index: mln/value/ops.hh --- mln/value/ops.hh (revision 1649) +++ mln/value/ops.hh (working copy) @@ -43,13 +43,14 @@ # include <mln/literal/ops.hh> # include <mln/metal/ret.hh> +/// Type trait for value sum. +# define mln_trait_value_sum_x(T, U) \ + typename mln::trait::value_< mln_trait_op_times(T,U) >::sum -# define mln_trait_value_sum_x(T, U) typename mln::trait::value_< mln_trait_op_times(T,U) >::sum - +/// Shortcut for type trait for value sum. # define mln_sum_x(T, U) mln_trait_value_sum_x(T, U) - // FIXME: In the definitions below, is that equiv or interop? Index: mln/fun/c.hh --- mln/fun/c.hh (revision 1649) +++ mln/fun/c.hh (working copy) @@ -30,7 +30,8 @@ /*! \file mln/fun/c.hh * - * \brief FIXME. + * \brief Encapsulate a plain (C language-like) pointer to function + * into a functor. */ # include <mln/fun/internal/selector.hh> Index: mln/fun/v2v/norm.hh --- mln/fun/v2v/norm.hh (revision 1649) +++ mln/fun/v2v/norm.hh (working copy) @@ -35,6 +35,8 @@ * \see mln/norm/. */ +// FIXME: Move to mln/fun/x2v/? + # include <mln/core/concept/function.hh> # include <mln/trait/value_.hh> Index: mln/norm/l1.hh --- mln/norm/l1.hh (revision 1649) +++ mln/norm/l1.hh (working copy) @@ -37,6 +37,8 @@ # include <mln/math/abs.hh> # include <mln/metal/vec.hh> +// FIXME: Use mln_sum_x (to be renamed as mln_sum_product) instead of +// mln_sum. namespace mln { Index: mln/norm/l2.hh --- mln/norm/l2.hh (revision 1649) +++ mln/norm/l2.hh (working copy) @@ -39,6 +39,9 @@ # include <mln/metal/vec.hh> +// FIXME: Use mln_sum_x (to be renamed as mln_sum_product) instead of +// mln_sum. + namespace mln {