Index: olena/oln/utils/copy.hh
--- olena/oln/utils/copy.hh Mon, 25 Aug 2003 11:47:33 +0200 burrus_n
(oln/i/29_copy.hh 1.7 640)
+++ olena/oln/utils/copy.hh Sat, 13 Mar 2004 18:06:17 +0100 van-vl_n
(oln/i/29_copy.hh 1.7 640)
@@ -1,4 +1,4 @@
-// Copyright (C) 2001, 2002, 2003 EPITA Research and Development
Laboratory
+// Copyright (C) 2001, 2002, 2003, 2004 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
@@ -28,15 +28,18 @@
#ifndef OLENA_UTILS_COPY_HH
# define OLENA_UTILS_COPY_HH
-// This file contains implementations of image's copy constructors
-//
-// / \ NEVER include this file unless you understand what
-// / ! \ it does and why you need it.
-// `-----'
-//
-// FIXME: should be replaced soon by a correct const image handling.
-// a detailed problem description can be found on:
-// http://www.lrde.epita.fr/cgi-bin/twiki/view/Projects/OlenaConstImages
+/* \file copy.hh
+**
+** \warning This file contains implementations of image's copy
constructors.
+**\verbatim
+** / \ NEVER include this file unless you understand what
+** / ! \ it does and why you need it.
+** `-----'
+**\endverbatim
+** \todo FIXME: should be replaced soon by a correct const image handling.
+** a detailed problem description can be found on:
+** http://www.lrde.epita.fr/cgi-bin/twiki/view/Projects/OlenaConstImages
+*/
namespace oln {
Index: olena/oln/utils/histogram.hh
--- olena/oln/utils/histogram.hh Wed, 11 Feb 2004 11:51:35 +0100
van-vl_n (oln/10_histogram. 1.6.1.14.1.6 640)
+++ olena/oln/utils/histogram.hh Sat, 13 Mar 2004 21:17:34 +0100
van-vl_n (oln/10_histogram. 1.6.1.14.1.6 640)
@@ -39,11 +39,12 @@
# include <vector>
namespace oln {
-
+ /// Namespace for utilities, such as statistic.
namespace utils {
+ /// Function within this namespace should not be used outside this
file.
namespace internal {
- //! Return the size of the space needed to explore the type T
+ //! Return the size of the space needed to explore the type T.
template <typename T>
struct img_max_size
{
@@ -82,11 +83,13 @@
};
} // end of namespace internal
+ /// Namespace for abstract utilities.
namespace abstract
{
- // FIXME: An image is inside the histogram. This is incorrect
- // because it is not exactly an image (we do not need any
- // border).
+ /*! Abstract base class for historgram.
+ **
+ ** \see oln::histogram
+ */
template<class T,
typename CPT,
class Exact = mlc::final>
@@ -96,25 +99,28 @@
typedef histogram<T, CPT, Exact> self_type;
typedef Exact exact_type;
typedef CPT cpt_type;
-
+ /// Put the number of occurrence of every value to zero.
void
clear()
{
this->exact().clear_impl();
}
-
+ /// Read the number of occurrence of \a v.
const CPT&
operator[](const T &v)const
{
return this->exact().at(v);
}
-
+ /// Read or write the number of occurrence of \a v.
CPT&
operator[](const T &v)
{
return this->exact().at(v);
}
-
+ /*! Build the histogram of an image.
+ **
+ ** \attention The histogram is not cleared.
+ */
template <class I>
void
init(const oln::abstract::image<I> &img)
@@ -124,6 +130,43 @@
};
} // end of namespace abstract
+ /*! Histogram.
+ **
+ ** This histogram uses an image of unsigned to store the value.
+ ** For example the histogram of an image<int_u8> will store the
+ ** number of occurrences in an image1d; an image<rgb_8> will store the
+ ** number of occurrences an image3d (because rgb_8 has 3 components).
+ **
+ ** \note FIXME: An image is inside the histogram. This is incorrect
+ ** because it is not exactly an image (we do not need any border).
+ **
+ ** \param T Type of the image.
+ ** \param CPT Type use to count the occurrences (unsinged).
+ ** \param V2P Concersion class to convert a value T to a point.
+ ** \param Exact Exact type of the histogram.
+ **
+ ** \see oln::abstract::histogram
+ **
+ ** \code
+ ** #include <oln/basics2d.hh>
+ ** #include <oln/utils/histogram.hh>
+ ** #include <ntg/all.hh>
+ ** #include <iostream>
+ **
+ ** int main()
+ ** {
+ ** oln::image2d<ntg::rgb_8> in = oln::io::load(IMG_IN "lena.ppm");
+ **
+ ** oln::utils::histogram<ntg::rgb_8> h(in);
+ **
+ ** ntg::rgb_8 pink(215, 129, 113);
+ **
+ ** // h[pink] = 14
+ ** std::cout << "Number of occurrences of the color (213, 129,
135): "
+ ** << h[pink] << std::endl;
+ ** }
+ ** \endcode
+ */
template<typename T,
typename CPT = unsigned,
class V2P = oln::convert::value_to_point<T>,
@@ -142,12 +185,14 @@
typedef abstract::histogram<T, CPT, self_type> upper_type;
typedef typename dim_traits<dim, CPT>::img_type img_type;
+ /// Empty histogram. The function Init(image) should be used
after this constructor.
histogram(const value_to_point_type & c2p = value_to_point_type()):
v2p_(c2p), img_(internal::img_max_size<input_type>()())
{
clear();
}
+ /// This compute the histogram of an image.
template <class I>
histogram(const oln::abstract::image<I> & input,
const value_to_point_type & v2p = value_to_point_type()):
@@ -157,6 +202,7 @@
init(input);
}
+ /// clear() should be called.
void
clear_impl()
{
@@ -165,18 +211,19 @@
img_[it] = ntg_zero_val(CPT);
}
+ /// operator[] should be called.
const CPT&
at(const T &v)const
{
return img_[v2p_(v)];
}
-
+ /// operator[] should be called.
CPT&
at(const T &v)
{
return img_[v2p_(v)];
}
-
+ /// impl() should be called.
template <class I>
void
init_impl(const oln::abstract::image<I> &img)
@@ -187,6 +234,7 @@
++img_[v2p_(img[it_img])];
}
+ /// Return the image of occurrence.
const img_type &
image() const
{
@@ -198,7 +246,16 @@
img_type img_;
};
- //Note: If there is no min an assertion will fail at the end of the
loop.
+ /*! Minimum value of an histogram.
+ **
+ ** It return the smaller value within the image used to build the
histogram.
+ **
+ ** \warning If there is no min an assertion will fail at the end of
the loop.
+ **
+ ** \note It can be slow when the histogram is sparse because it
iterate over a
+ ** large range of 0. Use histogram_min or histogram_minmax instead.
+ ** \see histogram_min
+ */
template< typename T, typename CPT, class Exact>
inline T
min(const abstract::histogram<T, CPT, Exact>& hist)
@@ -211,7 +268,16 @@
break;
return i;
}
- //Note: If there is no max an assertion will fail at the end of the
loop.
+ /*! Maximum value of an histogram.
+ **
+ ** It return the higher value within the image used to build the
histogram.
+ **
+ ** \warning If there is no min an assertion will fail at the end of
the loop.
+ **
+ ** \note It can be slow when the histogram is sparse because it
iterate over a
+ ** large range of 0. Use histogram_max or histogram_minmax instead.
+ ** \see histogram_max
+ */
template< typename T, typename CPT, class Exact>
inline T
max(const abstract::histogram<T, CPT, Exact>& hist)
@@ -225,26 +291,21 @@
return i;
}
-/* The two functions above can be slow when the histogram is sparse
- because they iterate over a large range of 0.
-
- It's inefficient to call them repeatedly while updating the
- histogram (that's typically the case in the morpho::fast::
- algorithms). Better use the specialized histograms below.
-
- ---
-
- The idea behind the min- and max-specialized histogram is to
- maintain worst min and max bounds while updating histogram. We
- don't maintain _exact_ min and max bounds, because this would
- involve some costly computation when removing values from the
- histogram and maybe this time will be lost if the removed value is
- reinsterted before max() or min() is called.
-
- So we update the _worst_ min and max bounds whenever the histogram
- value are accessed, and delay the _real_ min and max compuation
- until min() or max() is called. */
-
+ /*! Build the histogram and has quick min and max functions.
+ **
+ ** The idea behind the min- and max-specialized histogram is to
+ ** maintain worst min and max bounds while updating histogram. We
+ ** don't maintain _exact_ min and max bounds, because this would
+ ** involve some costly computation when removing values from the
+ ** histogram and maybe this time will be lost if the removed value is
+ ** reinserted before max() or min() is called.\n
+ ** So we update the _worst_ min and max bounds whenever the histogram
+ ** value are accessed, and delay the _real_ min and max computation
+ ** until min() or max() is called.
+ ** \see histogram
+ ** \see histogram_min
+ ** \see histogram_max
+ */
template< typename T,
typename CPT = unsigned,
class V2P = convert::value_to_point<T>,
@@ -256,6 +317,7 @@
private:
typedef typename ntg_is_a(T, ntg::non_vectorial)::ensure_type
ensure_type;
protected:
+ /// Maintain the worst min and max.
void
adjust(const T &idx)
{
@@ -280,7 +342,7 @@
upper_type(input, v2p),
min_(ntg_min_val(T)), max_(ntg_max_val(T)) {}
-
+ /// operator[] should be called.
const CPT&
at(const T& i) const
{
@@ -288,6 +350,7 @@
return img_[v2p_(i)];
}
+ /// operator[] should be called.
CPT&
at(const T& i)
{
@@ -295,6 +358,7 @@
return img_[v2p_(i)];
}
+ /// Quick function min.
T
min()
{
@@ -303,7 +367,7 @@
break;
return min_;
}
-
+ /// Quick function max.
T
max()
{
@@ -314,9 +378,12 @@
}
protected:
- T min_, max_; // indices of min and max elements
+ T min_, max_; ///< Indices of min and max elements.
};
-
+ /*! Build the histogram and has quick min function.
+ **
+ ** \see histogram_minmax
+ */
template< typename T,
typename CPT = unsigned,
class V2P = convert::value_to_point<T>,
@@ -328,6 +395,7 @@
private:
typedef typename ntg_is_a(T, ntg::non_vectorial)::ensure_type
ensure_type;
protected:
+ /// Maintain the worst min.
void
adjust(const T& idx)
{
@@ -349,20 +417,21 @@
const value_to_point_type & v2p = value_to_point_type()) :
upper_type(input, v2p), min_(ntg_min_val(T)) {}
-
+ /// operator[] should be called.
const CPT&
at(const T& i) const
{
return img_[v2p_(i)];
}
+ /// operator[] should be called.
CPT&
at(const T& i)
{
adjust(i);
return img_[v2p_(i)];
}
-
+ /// Quick function min.
T
min()
{
@@ -371,7 +440,7 @@
break;
return min_;
}
-
+ /// Return the min.
T
res()
{
@@ -379,9 +448,13 @@
}
protected:
- T min_; // index of min element
+ T min_; ///< Index of the worst min element.
};
+ /*! Build the histogram and has quick max function.
+ **
+ ** \see histogram_minmax
+ */
template< typename T,
typename CPT = unsigned,
class V2P = convert::value_to_point<T> ,
@@ -391,6 +464,7 @@
Exact>::ret>
{
protected:
+ /// Maintain the worst max.
void
adjust(const T& idx)
{
@@ -412,19 +486,21 @@
const value_to_point_type & v2p = value_to_point_type()) :
upper_type(input, v2p),max_(ntg_max_val(T)) {}
+ /// operator[] should be called.
const CPT&
at(const T& i) const
{
return img_[v2p_(i)];
}
+ /// operator[] should be called.
CPT&
at(const T& i)
{
adjust(i);
return img_[v2p_(i)];
}
-
+ /// Quick function max.
T
max()
{
@@ -433,7 +509,7 @@
break;
return max_;
}
-
+ /// Return the max.
T
res()
{
@@ -441,34 +517,45 @@
}
protected:
- T max_; // index of max element
+ T max_; ///< Index of the worst max element.
};
+ /// Minimum non-zero value of an histogram.
template< typename T, typename CPT, class V2P, class Exact >
inline T
min(histogram_minmax<T, CPT, V2P, Exact>& hist)
{
return hist.min();
}
+ /// Minimum non-zero value of an histogram.
template< typename T, typename CPT, class V2P, class Exact >
inline T
min(histogram_min<T, CPT, V2P, Exact>& hist)
{
return hist.min();
}
+ /// Maximum non-zero value of an histogram.
template< typename T, typename CPT, class V2P, class Exact >
inline T
max(histogram_minmax<T, CPT, V2P, Exact>& hist)
{
return hist.max();
}
+ /// Maximum non-zero value of an histogram.
template< typename T, typename CPT, class V2P, class Exact >
inline T
max(histogram_max<T, CPT, V2P, Exact>& hist)
{
return hist.max();
}
-
+ /*! Sort the values of an image, and store the result in a vector
+ **
+ ** This sort is efficient.
+ ** \arg im Image non_vectorial.
+ ** \arg v sorted vector at the end of the function.
+ ** \pre precondition(v.size() == im.npoints());
+ ** \pre A histogram of the image has to be possible.
+ */
template<class I>
void
distrib_sort(const oln::abstract::image<I>& im,
@@ -501,6 +588,14 @@
*(ptr[unsigned(im[p] - ntg_min_val(val))]++) = p;
}
+ /*! Inverted sort of the values of an image, and store the result
in a vector
+ **
+ ** This sort is efficient.
+ ** \arg im Image non_vectorial.
+ ** \arg v sorted vector at the end of the function.
+ ** \pre precondition(v.size() == im.npoints());
+ ** \pre A histogram of the image has to be possible.
+ */
template<class I>
void
distrib_sort_inv(const oln::abstract::image<I>& im,
@@ -526,7 +621,10 @@
*(ptr[unsigned(im[p] - ntg_min_val(val))]++) = p;
}
- // to select staticly the good distrib_sort
+ /*! Select staticly the good distrib_sort.
+ **
+ ** \param reverse If the sort should be reverted or not.
+ */
template <bool reverse>
struct select_distrib_sort
{
Index: olena/oln/utils/stat.hh
--- olena/oln/utils/stat.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n
(oln/9_stat.hh 1.5.1.9 640)
+++ olena/oln/utils/stat.hh Sat, 13 Mar 2004 20:50:57 +0100 van-vl_n
(oln/9_stat.hh 1.5.1.9 640)
@@ -1,4 +1,4 @@
-// Copyright (C) 2001, 2002, 2003 EPITA Research and Development
Laboratory
+// Copyright (C) 2001, 2002, 2003, 2004 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
@@ -35,6 +35,7 @@
namespace utils {
+ /// Unary function that stores the min and the max.
template< class T >
struct f_minmax : std::unary_function< const T&, void >
{
@@ -61,25 +62,28 @@
count_ = 0;
}
+ /// True if a value has been tested.
bool
valued() const
{
return count_;
}
+ /// Number of value has been tested.
size_t
count() const
{
return count_;
}
+ /// Minimum found.
const T
min() const
{
assertion(valued());
return min_;
}
-
+ /// Maximum found.
const T
max() const
{
@@ -93,6 +97,7 @@
T max_;
};
+ /// Computes the mean, the variance and store the min, the max.
template< class T, class C = ntg::float_s >
struct f_moments : f_minmax<T>
{
@@ -114,13 +119,14 @@
super::operator()(val);
}
+ /// Return the mean value.
const C
mean() const
{
assertion(this->valued());
return sum1_ / C(this->count());
}
-
+ /// Return the variance.
const C
variance() const
{
Index: olena/oln/utils/timer.hh
--- olena/oln/utils/timer.hh Fri, 07 Nov 2003 17:34:52 +0100 burrus_n
(oln/8_timer.hh 1.8 640)
+++ olena/oln/utils/timer.hh Sat, 13 Mar 2004 21:21:29 +0100 van-vl_n
(oln/8_timer.hh 1.8 640)
@@ -1,4 +1,4 @@
-// Copyright (C) 2001, 2002, 2003 EPITA Research and Development
Laboratory
+// Copyright (C) 2001, 2002, 2003, 2004 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
@@ -34,10 +34,16 @@
namespace oln {
namespace utils {
-
+ /*! Timer class.
+ */
class timer
{
public:
+ /*! Constructor.
+ **
+ ** \note The timer is not stopped, it is in a so-called 'unknown
state'.
+ ** Therefor, Restart can not be called.
+ */
timer()
{
status_ = e_unknown;
@@ -45,6 +51,10 @@
start_time_ = clock();
}
+ /*! Start the timer.
+ **
+ ** \pre The timer should not be running.
+ */
void
start()
{
@@ -54,7 +64,10 @@
status_ = e_running;
start_time_ = clock();
}
-
+ /*! Restart the timer.
+ **
+ ** \pre The timer should have been start at least one time.
+ */
float
restart()
{
@@ -64,6 +77,10 @@
return val;
}
+ /*! Resume the timer.
+ **
+ ** \pre The timer should be running.
+ */
void
resume()
{
@@ -72,6 +89,10 @@
start_time_ = clock();
}
+ /*! Stop the timer.
+ **
+ ** \pre The timer should be running.
+ */
float
stop()
{
@@ -82,7 +103,7 @@
return total_time();
}
- // Time since the last resume() or start()
+ /// Time since the last resume() or start().
float
last_time() const
{
@@ -93,6 +114,7 @@
float((clock() - start_time_)) / CLOCKS_PER_SEC;
}
+ /// Total time elapsed.
float
total_time() const
{
Index: olena/oln/utils/special_points.hh
--- olena/oln/utils/special_points.hh Tue, 10 Feb 2004 19:49:03 +0100
van-vl_n (oln/j/50_special_po 1.1 644)
+++ olena/oln/utils/special_points.hh Sat, 13 Mar 2004 21:22:12 +0100
van-vl_n (oln/j/50_special_po 1.1 644)
@@ -33,7 +33,7 @@
namespace oln {
namespace utils {
-
+ /// oln::utils::internal
namespace internal {
/*! Creates a point that is used as a state.
*
In attribute_closing_opening_map.hh:
** im1 = oln::morpho::slow::card_closing(im1, oln::neighb_c4(), 200);
** oln::save(im1, IMG_OUT "oln_morpho_fast_card_closing.ppm");
Dans attribute_closing_opening_map.hh, ne faut-il pas changer
les noms de fichiers *fast*.ppm en *slow*.ppm?
--
Niels
Please, try to correct apply.hh and traverse.hh.
There is many problems with \param and with \ref.
There is mamy English problems too, such as the wrong
usage of "we".
Index: olena/ChangeLog
from Niels Van Vliet <niels(a)lrde.epita.fr>
* olena/oln/convert/nrgbxyz.hh: Correct comments.
* olena/oln/convert/stretch.hh: Likewise.
* olena/oln/level/cc.hh: Likewise.
* olena/oln/morpho/gradient.inc: Likewise.
* olena/oln/morpho/attribute_closing_opening.hh: Likewise.
* olena/oln/morpho/attribute_union_find.hh: Likewise.
* olena/oln/topo/inter-pixel/inter-pixel.hh: Likewise.
* olena/oln/topo/inter-pixel/node.hh: Likewise.
* olena/oln/core/abstract/image_with_dim.hh: Likewise.
* olena/oln/core/impl/image_impl.hh: Likewise.
* olena/oln/morpho/attributes.hh: Likewise.
* olena/oln/utils/special_points.hh: Likewise.
Index: olena/oln/convert/nrgbxyz.hh
--- olena/oln/convert/nrgbxyz.hh Sat, 13 Mar 2004 17:45:05 +0100
van-vl_n (oln/16_nrgbxyz.hh 1.13 640)
+++ olena/oln/convert/nrgbxyz.hh Sun, 14 Mar 2004 18:40:08 +0100
van-vl_n (oln/16_nrgbxyz.hh 1.13 640)
@@ -52,7 +52,7 @@
/*! Functor for conversion from N-RGB to XYZ color space.
**
- ** \obsolete A composition should be performed with nrgb->rgb and
rgb->xyz. It has
+ ** \deprecated A composition should be performed with nrgb->rgb and
rgb->xyz. It has
** not been replaced within the function because a double
conversion 'reduces'
** the color space. See the following example:
** \code
@@ -112,7 +112,7 @@
/*! Conversion from N-RGB to XYZ color space.
**
- ** \obsolete A composition should be performed with nrgb->rgb and
rgb->xyz.
+ ** \deprecated A composition should be performed with nrgb->rgb and
rgb->xyz.
**
** \see f_nrgb_to_xyz for more information.
*/
@@ -127,7 +127,7 @@
/*! Functor for conversion from XYZ to N-RGB color space.
**
- ** \obsolete A composition should be performed with xyz->rgb and
rgb->nrgb.
+ ** \deprecated A composition should be performed with xyz->rgb and
rgb->nrgb.
**
** \see f_nrgb_to_xyz for more information.
*/
@@ -162,7 +162,7 @@
/*! Conversion from XYZ to N-RGB color space.
**
- ** \obsolete a composition should be performed with xyz->rgb and
rgb->nrgb.
+ ** \deprecated a composition should be performed with xyz->rgb and
rgb->nrgb.
**
** \see f_nrgb_to_xyz for more information.
*/
Index: olena/oln/convert/stretch.hh
--- olena/oln/convert/stretch.hh Sun, 14 Mar 2004 18:21:09 +0100 palma_g
(oln/f/51_stretch.hh 1.16 640)
+++ olena/oln/convert/stretch.hh Sun, 14 Mar 2004 18:46:17 +0100
van-vl_n (oln/f/51_stretch.hh 1.16 640)
@@ -92,7 +92,7 @@
/*! Stretch the value of an image.
**
** This function stretches values between \a min_in and \a max_in
- ** of an image \in, to a range that goes from \a min_out to \a max_out.
+ ** of an image \a in, to a range that goes from \a min_out to \a
max_out.
** \arg in Input image, must be have scalar values
** \arg min_in Lower bound of the range in the input. All values
smaller
** than min_in are converted to \a min_out.
Index: olena/oln/level/cc.hh
--- olena/oln/level/cc.hh Sun, 14 Mar 2004 18:21:09 +0100 palma_g
(oln/e/20_cc.hh 1.11.1.11 640)
+++ olena/oln/level/cc.hh Sun, 14 Mar 2004 18:47:51 +0100 van-vl_n
(oln/e/20_cc.hh 1.11.1.11 640)
@@ -61,7 +61,7 @@
** the connected components.
**
** It removes the small (in area) connected components of the upper
- ** level sets of \var{input} using \var{se} as structural element.
+ ** level sets of \a input using \a se as structural element.
**
** \ref The implementation uses front propagation.
**
Index: olena/oln/morpho/gradient.inc
--- olena/oln/morpho/gradient.inc Sun, 14 Mar 2004 18:21:09 +0100
palma_g (oln/43_gradient.i 1.15 640)
+++ olena/oln/morpho/gradient.inc Sun, 14 Mar 2004 18:51:26 +0100
van-vl_n (oln/43_gradient.i 1.15 640)
@@ -201,7 +201,7 @@
** IMG_OUT "oln_morpho_external_gradient.pbm");
** return 0;
** }
-** \encode
+** \endcode
**
** \image html lena256_pgm.png
** \image latex lena256_pgm.png
Index: olena/oln/morpho/attribute_closing_opening.hh
--- olena/oln/morpho/attribute_closing_opening.hh Sun, 14 Mar 2004
18:21:09 +0100 palma_g (oln/q/49_attribute_ 1.20 640)
+++ olena/oln/morpho/attribute_closing_opening.hh Sun, 14 Mar 2004
18:52:18 +0100 van-vl_n (oln/q/49_attribute_ 1.20 640)
@@ -30,9 +30,7 @@
#include <oln/morpho/attribute_union_find.hh>
-/*! \namespace oln
-** \brief oln namespace
-*/
+
namespace oln {
/*! \namespace oln::morpho
** \brief oln::morpho namespace
Index: olena/oln/morpho/attribute_union_find.hh
--- olena/oln/morpho/attribute_union_find.hh Sun, 14 Mar 2004 18:15:46
+0100 van-vl_n (oln/q/50_attribute_ 1.16 640)
+++ olena/oln/morpho/attribute_union_find.hh Sun, 14 Mar 2004 18:42:36
+0100 van-vl_n (oln/q/50_attribute_ 1.16 640)
@@ -49,7 +49,7 @@
** \param ATTRIBUTE Exact type of attribute to use.
** \param Env Type of environment to use.
**
- ** \Note FIXME: a similar class is defined in oln/topo/tarjan/union.hh
+ ** \note FIXME: a similar class is defined in oln/topo/tarjan/union.hh
** (oln::topo::tarjan::tarjan_set).
*/
template<class T, class ATTRIBUTE, class Env = attr_env_type(ATTRIBUTE)>
Index: olena/oln/topo/inter-pixel/inter-pixel.hh
--- olena/oln/topo/inter-pixel/inter-pixel.hh Sun, 14 Mar 2004 18:15:46
+0100 van-vl_n (oln/r/34_inter-pixe 1.13 640)
+++ olena/oln/topo/inter-pixel/inter-pixel.hh Sun, 14 Mar 2004 18:27:59
+0100 van-vl_n (oln/r/34_inter-pixe 1.13 640)
@@ -68,6 +68,7 @@
** // (10,11): north west south
** // (11,14): north west south
** }
+ ** \endcode
** \todo FIXME: Test the output values in the tests.
*/
template <class I>
Index: olena/oln/topo/inter-pixel/node.hh
--- olena/oln/topo/inter-pixel/node.hh Sun, 14 Mar 2004 18:15:46 +0100
van-vl_n (oln/r/46_node.hh 1.5 640)
+++ olena/oln/topo/inter-pixel/node.hh Sun, 14 Mar 2004 18:43:28 +0100
van-vl_n (oln/r/46_node.hh 1.5 640)
@@ -67,7 +67,7 @@
data_[i] = true;
}
- /// Return true if the direction \i joins the node.
+ /// Return true if the direction \a i joins the node.
bool
get(dir_type i) const
{
Index: olena/oln/core/abstract/image_with_dim.hh
--- olena/oln/core/abstract/image_with_dim.hh Thu, 11 Mar 2004 20:19:51
+0100 thivol_d (oln/t/26_image_with 1.20 600)
+++ olena/oln/core/abstract/image_with_dim.hh Sun, 14 Mar 2004 18:30:27
+0100 van-vl_n (oln/t/26_image_with 1.20 600)
@@ -151,11 +151,7 @@
namespace abstract {
- /*! \class image_with_dim<1, Exact>: virtual public image<Exact>
- **
- ** The specialized version for image1d.
- */
-
+ /// The specialized version for image1d.
template <class Exact>
class image_with_dim<1, Exact>: virtual public image<Exact>
{
@@ -280,12 +276,7 @@
- /*! \class image_with_dim<2, Exact>: virtual public image<Exact>
- **
- ** The specialized version for image2d.
- */
-
-
+ /// The specialized version for image2d.
template <class Exact>
class image_with_dim<2, Exact>: virtual public image<Exact>
{
@@ -423,10 +414,7 @@
}; // end of bi-dimensional specialization
- /*! \class image_with_dim<3, Exact>: virtual public image<Exact>
- **
- ** The specialized version for image3d.
- */
+ /// The specialized version for image3d.
template <class Exact>
class image_with_dim<3, Exact>: virtual public image<Exact>
Index: olena/oln/core/impl/image_impl.hh
--- olena/oln/core/impl/image_impl.hh Fri, 12 Mar 2004 20:17:58 +0100
thivol_d (oln/t/29_image_impl 1.17 640)
+++ olena/oln/core/impl/image_impl.hh Sun, 14 Mar 2004 18:41:06 +0100
van-vl_n (oln/t/29_image_impl 1.17 640)
@@ -111,7 +111,7 @@
return this->exact().at_(p);
}
- /// Return a reference to the value stored at \p.
+ /// Return a reference to the value stored at \a p.
value_type&
at(const point_type& p)
Index: olena/oln/morpho/attributes.hh
--- olena/oln/morpho/attributes.hh Fri, 12 Mar 2004 13:29:59 +0100
palma_g (oln/j/45_attributes 1.7 644)
+++ olena/oln/morpho/attributes.hh Sun, 14 Mar 2004 18:26:35 +0100
van-vl_n (oln/j/45_attributes 1.7 644)
@@ -183,9 +183,9 @@
};
/*!
- ** \brief < operator
+ ** \brief "<" operator
**
- ** This is a static dispatcher for the < operator.
+ ** This is a static dispatcher for the "<" operator.
** This method is abstract.
*/
bool operator<(const lambda_type &lambda) const
@@ -282,9 +282,9 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
- ** This is an implementation of the < operator. Override this
+ ** This is an implementation of the "<" operator. Override this
** method to provide a new implementation of this operator.
** \warning This method SHOULDN'T be called.
*/
@@ -443,7 +443,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -693,7 +693,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -811,7 +811,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -927,7 +927,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -1088,7 +1088,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -1239,7 +1239,7 @@
};
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -1408,7 +1408,7 @@
}
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
@@ -1567,7 +1567,7 @@
}
/*!
- ** \brief < operator implementation.
+ ** \brief "<" operator implementation.
**
** This is an implementation of the += operator. Override this
** method to provide a new implementation of this operator.
Index: olena/oln/utils/special_points.hh
--- olena/oln/utils/special_points.hh Sat, 13 Mar 2004 21:28:08 +0100
van-vl_n (oln/j/50_special_po 1.2 644)
+++ olena/oln/utils/special_points.hh Sun, 14 Mar 2004 18:28:50 +0100
van-vl_n (oln/j/50_special_po 1.2 644)
@@ -33,7 +33,7 @@
namespace oln {
namespace utils {
- /// oln::utils::internal
+
namespace internal {
/*! Creates a point that is used as a state.
*
The following message is a courtesy copy of an article
that has been posted to epita.cours.compile as well.
2004-03-16 Akim Demaille <akim(a)epita.fr>
* assignments.texi (Documentation Style): Document
flyspell-prog-mode, Doxygen limitations (capitalization of
sentences), and namespace documentation location.
--- /home/akim/www/compil/assignments.txt 2004-03-16 09:13:35.000000000 +0100
+++ assignments.txt 2004-03-16 10:16:23.000000000 +0100
@@ -1565,6 +1565,26 @@
2.3.7 Documentation Style
-------------------------
+ -- Rule: Write correct English
+ Nowadays most editors provide interactive spell checking including for
+ programs (strings and comments). For instance, see `flyspell-mode' in
+ Emacs, and in particular the `flyspell-prog-mode'. To trigger it
+ automatically, install the following in your `~/.emacs.el':
+
+ (add-hook 'c-mode-hook 'flyspell-prog-mode 1)
+ (add-hook 'c++-mode-hook 'flyspell-prog-mode 1)
+ (add-hook 'cperl-mode-hook 'flyspell-prog-mode 1)
+ (add-hook 'sh-mode-hook 'flyspell-prog-mode 1)
+ (add-hook 'makefile-mode-hook 'flyspell-prog-mode 1)
+
+ and so forth.
+
+ End comments with a period.
+
+ For documentation as for any other kind of writing, the shorter, the
+ better: hunt useless words. *Note The Elements of Style::, for an
+ excellent set of writing guidelines.
+
-- Rule: Use the Imperative
Use the imperative when documenting, as if you were giving order to the
function or entity you are describing. When describing a function,
@@ -1581,7 +1601,7 @@
/// Swap the two references and return the first.
ref& swap (ref& other);
- The same rules apply to writing ChangeLogs.
+ The same rules apply to ChangeLogs.
-- Rule: Use `rebox.el' to markup paragraphs
Often one wants to leave a clear markup to separate different matters.
@@ -1599,13 +1619,28 @@
| Comments end with a period. |
`-----------------------------*/
- -- Rule: Prefer Doxygen Documentation to plain comments
- We use Doxygen (*note Doxygen::) to maintain the developer
- documentation of the Tiger Compiler.
-
-- Rule: Write Documentation in Doxygen
- Documentation is a genuine part of programming, just as testing. The
- quality of this documentation can change the grade.
+ Documentation is a genuine part of programming, just as testing. We
+ use Doxygen (*note Doxygen::) to maintain the developer documentation
+ of the Tiger Compiler. The quality of this documentation can change
+ the grade.
+
+ Beware that Doxygen puts the first letter of the documentation in upper
+ case. As a result,
+
+ /// \file ast/arrayexp.hh
+ /// \brief ast::ArrayExp declaration.
+
+ will not work properly, since `ast::ArrayExp' will be transformed into
+ `Ast::ArrayExp' by Doxygen, which will not be recognized as an entity
+ name. As a workaround, write the slightly longer:
+
+ /// \file ast/arrayexp.hh
+ /// \brief Declaration of ast::ArrayExp.
+
+ -- Rule: Document namespaces in `lib*.hh' files
+ -- Rule: Document classes in their `*.hh' file
+ There must be a single location, that's our standard.
-- Rule: Use `\directive'
Prefer backslash (`\') to the commercial at (`@') to specify
