oln 10.93: add comments, correct older ones - Olena-patches

15 Mar 2004

Index: olena/ChangeLog
from  Damien Thivolle  damien@lrde.epita.fr
    * olena/oln/core/apply.hh: Correct comments.
    * olena/oln/core/compose.hh: Correct comments.
    * olena/oln/io/file.hh: Add comments.
    * olena/oln/io/gz.hh: Likewise.
    * olena/oln/io/gz_stream.hh: Likewise.
    * olena/oln/io/pnm_read_3d.hh: Likewise.
    * olena/oln/io/pnm_read.hh: Likewise.
    * olena/oln/io/pnm_write_3d.hh: Likewise.
    * olena/oln/io/pnm_write.hh: Likewise.
    * olena/oln/io/pnm_common.hh: Likewise.
    * olena/oln/io/stream_wrapper.hh: Likewise.
    * olena/oln/io/pnm_read_data.hh: Likewise. 
    * olena/oln/io/pnm_write_data.hh: Likewise.
    * olena/oln/io/pnm_read_2d.hh: Likewise.
    * olena/oln/io/pnm_write_2d.hh: Likewise.
Index: olena/oln/core/apply.hh

--- olena/oln/core/apply.hh Fri, 12 Mar 2004 20:17:58 +0100 thivol_d (oln/d/39_apply.hh 1.15 600)
+++ olena/oln/core/apply.hh Mon, 15 Mar 2004 18:57:19 +0100 thivol_d (oln/d/39_apply.hh 1.15 600)
@@ -40,9 +40,36 @@
   | Unary |
   `------*/
-  /*! \brief Standard unary \a apply procedure. Apply function f to each
-  ** element of input.
+  /*! \brief Standard unary \a apply procedure. Apply a function \a f to each
+  ** element of \a input.
+  **
+  ** Sample of code : Threshold the value of the image.
+  **
+  ** \code
+  ** #include <oln/basics2d.hh>
+  ** #include <oln/level/threshold.hh>
+  ** #include <ntg/all.hh>
+  ** using namespace ntg;
+  ** int main()
+  ** {
+  **   oln::image2d<int_u8> in = oln::load(IMG_IN "lena256.pgm");
+  **   int_u8 th	= 127;
+  **   rgb_8 low	= rgb_8(100, 0, 0);
+  **   rgb_8 height	= rgb_8(0, 200, 255);
+  **
+  **   oln::image2d<rgb_8> out
+  **     = apply(oln::level::threshold<int_u8, rgb_8 >(th, low, height),
+  ** 	    in);
+  **   save(out, IMG_OUT "oln_level_threshold.ppm");
+  ** }
+  ** \endcode
+  ** \image html lena256_pgm.png
+  ** \image latex lena256_pgm.png
+  ** =>
+  ** \image html oln_level_threshold.png
+  ** \image latex oln_level_threshold.png
   */
+
   template<class AdaptableUnaryFun, class I> inline
   typename mute<I, typename AdaptableUnaryFun::result_type>::ret
   apply(AdaptableUnaryFun f, const abstract::image<I>& input)
@@ -55,9 +82,9 @@
   }
-  /*! \brief Standard unary \a apply procedure. Apply function f to each
-  ** element of input, the function is passed as a type
-  ** and we build it ourself. 
+  /*! \brief Standard unary \a apply procedure. Apply a function \a f to each
+  ** element of \a input, the function is passed as a type
+  ** and is instantiated.
   */
   template<class AdaptableUnaryFun, class I> inline
   typename mute<I, typename AdaptableUnaryFun::result_type>::ret
@@ -67,10 +94,10 @@
   }
-  /*! \brief Standard unary \a apply procedure. Apply function f to each
-  ** element of input, the function is passed as a type
-  ** and we build it ourself. For template functions passed as template-id,
-  ** we need to instantiate the function for the type of the abstract::image.
+  /*! \brief Standard unary \a apply procedure. Apply function \a f to each
+  ** element of \a input, the function is passed as a type
+  ** and is instantiated. For template functions passed as template-id,
+  ** one need to instantiate the function for the type of the abstract::image.
   */
   template<template<class> class AdaptableUnaryFun,
       class I> inline
@@ -91,8 +118,8 @@
   ** \todo FIXME: Don't we want to name these functions 'apply()' too? 
   */
-  /*! \brief Standard binary \a apply procedure. Apply function f to each
-  ** element of input1 and input2. 
+  /*! \brief Standard binary \a apply procedure. Apply function \a f to each
+  ** element of \a input1 and \a input2. 
   **
   ** \todo FIXME: Don't we want to name these functions 'apply()' too?
   */
@@ -110,9 +137,9 @@
   }
-  /*! \brief Standard binary \a apply procedure. Apply function f to each
-  ** element of input1 and input2. The function is passed as a type
-  ** and we build it ourself.
+  /*! \brief Standard binary \a apply procedure. Apply function \a f to each
+  ** element of \a input1 and \a input2. The function is passed as a type
+  ** and is instantiated.
   **
   ** \todo FIXME: Don't we want to name these functions 'apply()' too?
   */
@@ -123,10 +150,10 @@
     return apply2(AdaptableBinaryFun(), input1, input2);
   }
-  /*! \brief Standard binary \a apply procedure. Apply function f to each
-  ** element of input1 and input2. The function is passed as a type
-  ** and we build it ourself. For template functions passed as template-id,
-  ** we need to instantiate the function for the type of the 
+  /*! \brief Standard binary \a apply procedure. Apply function \a f to each
+  ** element of \a input1 and \a input2. The function is passed as a type
+  ** and is instantiated. For template functions passed as template-id,
+  ** one need to instantiate the function for the type of the 
   ** abstract::images.
   **
   ** \todo FIXME: Don't we want to name these functions 'apply()' too?
@@ -143,14 +170,13 @@
   }
-  /*! \brief Standard binary \a apply procedure. Apply function f to each
-  ** element of input1 and input2. The function is passed as a type
-  ** and we build it ourself. For template functions passed as template-id,
-  ** we need to instantiate the function for the type of the 
+  /*! \brief Standard binary \a apply procedure. Apply function \a f to each
+  ** element of \a input1 and \a input2. The function is passed as a type
+  ** and is instantiated. For template functions passed as template-id,
+  ** one need to instantiate the function for the type of the 
   ** abstract::images.
   **
   ** \todo FIXME: Don't we want to name these functions 'apply()' too?\n
-  ** FIXME: Workaround for g++-2.95 bug.
   */
   template<template <class> class AdaptableBinaryFun,
            class I> inline
@@ -168,9 +194,9 @@
   | self unary |
   `-----------*/
-  /*! \brief Main apply_self() function. Note we require a UnaryFun only,
-  ** not a AdaptableUnaryFunc, because as we overwrite an abstract::image
-  ** we already know the output type.
+  /*! \brief Main \a apply_self() function. Note only a UnaryFun is required,
+  ** not a AdaptableUnaryFunc, because as an abstract::image is overwritten,
+  ** the output type is already known.
   */
   template<class UnaryFun, class I> inline
   abstract::image<I>& apply_self(UnaryFun f, abstract::image<I>& input)
@@ -181,9 +207,9 @@
   }
-  /*! \brief Main apply_self() function. Note we require a UnaryFun only,
-  ** not a AdaptableUnaryFunc, because as we overwrite an abstract::image
-  ** we already know the output type. We instantiate the function ourself.
+  /*! \brief Only a UnaryFun is required,
+  ** not a AdaptableUnaryFunc, because as an abstract::image is overwritten,
+  ** the output type is already known. The function is instantiated.
   */
   template<class UnaryFun, class I> inline
   abstract::image<I>& apply_self(abstract::image<I>& input)
@@ -192,11 +218,9 @@
   }
-  /*! \brief Main apply_self() function. Note we require a UnaryFun only,
-  ** not a AdaptableUnaryFunc, because as we overwrite an abstract::image
-  ** we already know the output type. We instantiate the function ourself.
-  **
-  ** \todo FIXME: Workaround for g++-2.95 bug.
+  /*! \brief Only a UnaryFun is required,
+  ** not a AdaptableUnaryFunc, because as an abstract::image is overwritten,
+  ** the output type is already know. The function is instantiated.
   */
   template<template<class> class UnaryFun, class I> inline
   abstract::image<I>& apply_self(abstract::image<I>& input)
@@ -211,7 +235,7 @@
   | self binary |
   `------------*/
-  /*! \brief Main apply2_exact() function.
+  /*! \brief Main \a apply2_exact() function.
   **
   ** \see apply_self()
   */
@@ -226,7 +250,7 @@
   }
-  /*! \brief We instantiate the function ourself.
+  /*! \brief The function is instantiated.
   **
   ** \see apply_self()
   */
@@ -237,10 +261,8 @@
   }
-  /*! \brief If the function is passed as a template-id, we 
-  ** Instantiate it for the type of the input elements.
-  **
-  ** \todo FIXME: Workaround for g++-2.95 bug.
+  /*! \brief If the function is passed as a template-id, it is 
+  ** instantiated for the type of the input elements.
   **
   ** \see apply_self()
   */
@@ -253,9 +275,7 @@
   }
-  /*! apply2_self() if I1==I2 and the UnaryFun has only one parameter.
-  **
-  ** \todo FIXME: Workaround for g++-2.95 bug.
+  /*! \brief If \a I1 == \a I2 and the UnaryFun has only one parameter.
   **
   ** \see apply_self()
   */
Index: olena/oln/core/compose.hh
--- olena/oln/core/compose.hh Fri, 12 Mar 2004 20:17:58 +0100 thivol_d (oln/c/22_compose.hh 1.6 600)
+++ olena/oln/core/compose.hh Mon, 15 Mar 2004 14:03:43 +0100 thivol_d (oln/c/22_compose.hh 1.6 600)
@@ -37,7 +37,7 @@
     /*! \class compose_uu_
     **
     ** The operator () of this class performs a composition between
-    ** two unary functors F1 & F2.
+    ** two unary functors \a F1 & \a F2.
     */
template< class F1, class F2 >
@@ -65,7 +65,7 @@
     /*! \class compose_ub_
     **
     ** The operator () of this class performs a composition between
-    ** an unary functor F1 and a binary functor F2.
+    ** a unary functor \a F1 and a binary functor \a F2.
     */
@@ -96,7 +96,7 @@
     /*! \class compose_bu_
     **
     ** The operator () of this class performs a composition between
-    ** a binary functor F1 and an unary functor F2.
+    ** a binary functor \a F1 and an unary functor \a F2.
     */
template< class F1, class F2 >
@@ -126,7 +126,7 @@
   }
-  /// Compose two unary functors F1 & F2.
+  /// Compose two unary functors \a F1 & \a F2.
   template<class UF1, class UF2>
   internal::compose_uu_<UF1, UF2>
   compose_uu(const UF1& f1, const UF2& f2)
@@ -134,7 +134,7 @@
     return internal::compose_uu_<UF1, UF2>(f1, f2);
   }
-  /// Compose an unary functors F1 with a binary functor F2.
+  /// Compose a unary functor \a F1 with a binary functor \a F2.
   template<class UF1, class BF2>
   internal::compose_ub_<UF1, BF2>
   compose_ub(const UF1& f1, const BF2& f2)
@@ -142,7 +142,7 @@
     return internal::compose_ub_<UF1, BF2>(f1, f2);
   }
-  /// Compose a binary functor F1 and an unary functor F2.
+  /// Compose a binary functor \a F1 and an unary functor \a F2.
   template<class BF1, class UF2>
   internal::compose_bu_<BF1, UF2>
   compose_bu(const BF1& f1, const UF2& f2)
Index: olena/oln/io/file.hh
--- olena/oln/io/file.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/b/17_file.hh 1.5 600)
+++ olena/oln/io/file.hh Mon, 15 Mar 2004 19:55:12 +0100 thivol_d (oln/b/17_file.hh 1.5 600)
@@ -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
@@ -40,6 +40,11 @@
namespace internal {
+      /*! \class stream_wrapper<StreamFile>
+      **
+      ** Specialized version for StreamFile.
+      */
+      
       template<>
       struct stream_wrapper<StreamFile>
       {
@@ -49,12 +54,14 @@
      static const std::string name_("file:"); return name_; 
    }
+	
    static bool 
    knows_ext(const std::string&) // knows all extensions
    { 
      return true; 
    }
+	/// Open a input stream on the file named \a name. Return 0 on failure.
    static std::istream* 
    wrap_in(std::string& name)
    {
@@ -65,6 +72,7 @@
      return 0;
    }
+	/// Open a output stream on the file named \a name. Return 0 on failure.
    static std::ostream* 
    wrap_out(std::string& name)
    {
@@ -75,6 +83,10 @@
      return 0;
    }
+	/*! \brief Insert in \a names all the files that have the same 
+	** suffix as \a name in the \a name or the current directory.
+	*/
+
    static void 
    find(std::liststd::string& names, const std::string& name)
    {
Index: olena/oln/io/gz.hh
--- olena/oln/io/gz.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/f/16_gz.hh 1.6 600)
+++ olena/oln/io/gz.hh Mon, 15 Mar 2004 18:58:29 +0100 thivol_d (oln/f/16_gz.hh 1.6 600)
@@ -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
@@ -37,9 +37,18 @@
namespace internal {
+
+      /*! \class stream_wrapper<StreamGz>
+      **
+      ** Specialized version for StreamGz.
+      */
+      
       template<>
       struct stream_wrapper<StreamGz>
       {
+	
+	/// Return "gz:"
+
    static const std::string& 
    name()
    { 
@@ -47,12 +56,16 @@
      return name_; 
    }
+	/// Return true if \a ext == "gz" or \a ext == "z'
+	
    static bool 
    knows_ext(const std::string& ext)
    { 
      return ext == "gz" || ext == "z"; 
    }
+	
+	/// Delete the file extension of \a name.
    static void 
    adjust_name(std::string& name)
    {
@@ -61,6 +74,10 @@
        name.erase(name.rfind('.'));
    }
+	/*! \brief Open a input stream on \a name then return it.
+	** On failure \a wrap_in returns 0.
+	*/
+
    static std::istream* 
    wrap_in(std::string& name)
    {
@@ -74,6 +91,9 @@
      return 0;
    }
+	/*! \brief Open a output stream on \a name then return it.
+	** On failure \a wrap_out returns 0.
+	*/
    static std::ostream* 
    wrap_out(std::string& name)
    {
Index: olena/oln/io/gz_stream.hh
--- olena/oln/io/gz_stream.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/f/17_gz_stream. 1.9 600)
+++ olena/oln/io/gz_stream.hh Mon, 15 Mar 2004 19:00:02 +0100 thivol_d (oln/f/17_gz_stream. 1.9 600)
@@ -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
@@ -39,12 +39,21 @@
namespace io {
+    /*! \namespace gz
+    ** \brief gz namespace
+    */
     namespace gz {
+
+      /*! \class zfilebuf
+      **
+      ** Performs operation on compressed files.
+      */
       class zfilebuf : public std::streambuf
       {
       public:
+	
    zfilebuf() : file(0),  mode(0),  own_file_descriptor(0)
    {
      inbuf = new char[lenbuf];
@@ -62,6 +71,10 @@
        close();
    }
+
+	/*! \brief Return a stream on the file \a name regarding
+	** the opening mode: \a io_mode.
+	*/
    zfilebuf*
    open(const char *name, int io_mode)
    {
@@ -107,6 +120,9 @@
      return this;
    }
+	/*! \brief Attach a stream on \a file_descriptor regarding
+	** the opening mode: \a io_mode.
+	*/
    zfilebuf*
    attach(int file_descriptor, int io_mode)
    {
@@ -152,6 +168,7 @@
      return this;
    }
+	/// Close the stream.
    zfilebuf*
    close()
    {
@@ -164,6 +181,7 @@
      return this;
    }
+	
    int 
    setcompressionlevel(short comp_level)
    {
@@ -176,6 +194,7 @@
      return gzsetparams(file, -2, comp_strategy);
    }
+	/// Return true if the stream is open, false otherwise.
    inline int 
    is_open() const 
    { return (file != 0); }
@@ -186,6 +205,7 @@
      return std::streampos(gzseek(file, off, dir));
    }
+	/// Flush the buffer associated to the stream.
    virtual int 
    sync()
    {
@@ -196,6 +216,9 @@
protected:
+	/*! \brief Return the next character in the stream.
+	** On failure, \a EOF is returned.
+	*/
    virtual int 
    underflow()
    {
@@ -218,6 +241,10 @@
      return (unsigned char) *gptr();
    }
+	/*! \brief Flush the output buffer associated to the stream 
+	** then write \a c. On failure, \a EOF is returned.
+	*/
+	
    virtual int 
    overflow(int c = EOF)
    {
@@ -247,6 +274,7 @@
    char *outbuf;
    static const int lenbuf = 16 * 1024;
+	/// Flush the output buffer
    int 
    flushbuf()
    {
@@ -261,7 +289,7 @@
      setp(outbuf, outbuf + lenbuf);
      return 0;
    }
-
+	/// Fill the input buffer.
    int 
    fillbuf()
    {
@@ -273,6 +301,11 @@
};
+      /*! \class zfilestream_common
+      **
+      ** Define an interface for compressed file stream manipulation.
+      */
+      
       class zfilestream_common : virtual public std::ios
       {
    friend class zifstream;
@@ -283,6 +316,9 @@
       public:
    virtual ~zfilestream_common() {}
+	/*! \brief Open the stream on the file descriptor:
+	** \a fd regarding the opening mode.
+	*/
    void 
    attach(int fd, int io_mode)
    {
@@ -292,6 +328,9 @@
        clear();
    }
+	/*! \brief Open the stream on the file named \a name
+	** regarding the opening mode.
+	*/
    void 
    open(const char *name, int io_mode)
    {
@@ -301,6 +340,7 @@
        clear();
    }
+	/// Close the current stream.
    void 
    close()
    {
@@ -309,6 +349,7 @@
    }
protected:
+	/// Prevent instantiation.
    zfilestream_common() :  std::ios(zfilestream_common::rdbuf())
    { }
@@ -323,6 +364,11 @@
    zfilebuf buffer;
       };
+
+      /*! \class zifstream
+      **
+      ** Read only zstream.
+      */
       class zifstream : public zfilestream_common, public std::istream
       {
       public:
@@ -332,12 +378,14 @@
      clear(std::ios::badbit);
    }
+	/// Open a read only stream on the file named \a name.
    zifstream(const char *name, int io_mode = std::ios::in) :
      std::istream(zfilestream_common::rdbuf())
    {
      zfilestream_common::open(name, io_mode);
    }
+	/// Open a read only stream on the file descriptor \a fd.
    zifstream(int fd, int io_mode = std::ios::in) :
      std::istream(zfilestream_common::rdbuf())
    {
@@ -356,12 +404,14 @@
      clear(std::ios::badbit);
    }
+	/// Open a write only stream on the file named \a name.
    zofstream(const char *name, int io_mode = std::ios::out) :
      std::ostream(zfilestream_common::rdbuf())
    {
      zfilestream_common::open(name, io_mode);
    }
+	/// Open a write only stream on the file descriptor \a fd.
    zofstream(int fd, int io_mode = std::ios::out) :
      std::ostream(zfilestream_common::rdbuf())
    {
@@ -376,12 +426,18 @@
       template <class T>
       class zomanip;
+      /// Apply a function on \a s via the operator <<.
       template <class T>
       zofstream&
       operator<<(zofstream &s, const zomanip<T> &m) {
    return (*m.func)(s, m.val);
       }
+      
+      /*! \class zomanip
+      **
+      ** Define a pair func / val to perform manipulation on zofstream.
+      */
       template<class T> class zomanip
       {		
    friend zofstream &operator<< <T>(zofstream &, const zomanip<T> &);
@@ -392,12 +448,15 @@
    T val;
       };
+      
+      /// Set the compression level of \a s to \a l.
       inline zofstream&
       setcompressionlevel(zofstream &s, int l) {
    (s.rdbuf())->setcompressionlevel(l);
    return s;
       }
+      /// Set the compression strategy of \a s to \a l.
       inline zofstream&
       setcompressionstrategy(zofstream &s, int l)
       {
@@ -405,12 +464,14 @@
    return s;
       }
+      /// Specialized version for zomanip<int>
       inline zomanip<int>
       setcompressionlevel(int l)
       {
    return zomanip<int>(&setcompressionlevel,l);
       }
+      /// Specialized version for zomanip<int>
       inline zomanip<int>
       setcompressionstrategy(int l)
       {
Index: olena/oln/io/pnm_read_3d.hh
--- olena/oln/io/pnm_read_3d.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/b/11_pnm_read3d 1.13 600)
+++ olena/oln/io/pnm_read_3d.hh Mon, 15 Mar 2004 19:02:17 +0100 thivol_d (oln/b/11_pnm_read3d 1.13 600)
@@ -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
@@ -47,9 +47,13 @@
       | pnm_reader3d (Any) |
       `-------------------*/
-      // Only PnmRaw images can store more than one 2d image. The
-      // format is simple: each slice is stored as a bi-dimensional
-      // image.
+      /*! \class pnm_reader<ReadPnmRaw, 3, P, I>
+      **
+      ** Specialized version for 3d image.
+      ** Only PnmRaw images can store more than one 2d image. The
+      ** format is simple: each slice is stored as a bi-dimensional
+      ** image.
+      */
template <pnm_type P, class I>
       struct pnm_reader<ReadPnmRaw, 3, P, I>
@@ -70,6 +74,11 @@
      return reader_2d::knows_ext(ext);
    }
+
+	/*! \brief Initialize \a im and return true if \a in
+	** is a valid pnm file format, return false otherwise.
+	*/
+
    static bool 
    read(std::istream& in, I& im)
    {
@@ -114,6 +123,8 @@
    }
private:
+	
+	/// Function used in \a read method.
    static void 
    to_image3d_(std::list<image2d_type*>& image2d_list, I& output)
    {
Index: olena/oln/io/pnm_read.hh
--- olena/oln/io/pnm_read.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/b/16_pnm_read.h 1.9.1.10 600)
+++ olena/oln/io/pnm_read.hh Mon, 15 Mar 2004 11:58:34 +0100 thivol_d (oln/b/16_pnm_read.h 1.9.1.10 600)
@@ -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
@@ -46,6 +46,11 @@
       | default pnm_reader |
       `-------------------*/
+      /*! \class pnm_reader
+      **
+      ** Default version.
+      */
+      
       template <reader_id R, unsigned Dim, pnm_type V, class I>
       struct pnm_reader
       {
@@ -72,11 +77,21 @@
       | reader for pnm |
       `---------------*/
+      /*! \class image_reader<ReadPnmPlain, I>
+      **
+      ** Specialized version for ReadPnmPlain
+      */
+
       template <class I>
       struct image_reader<ReadPnmPlain, I>
    : public pnm_reader<ReadPnmPlain, I::dim, get_pnm_type<I>::ret, I>
       {};
+      /*! \class image_reader<ReadPnmRaw, I>
+      **
+      ** Specialized version for ReadPnmRaw
+      */
+
       template <class I>
       struct image_reader<ReadPnmRaw, I>
    : public pnm_reader<ReadPnmRaw, I::dim, get_pnm_type<I>::ret, I>
Index: olena/oln/io/pnm_write_3d.hh
--- olena/oln/io/pnm_write_3d.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/b/9_pnm_write3 1.1.1.13 600)
+++ olena/oln/io/pnm_write_3d.hh Mon, 15 Mar 2004 13:45:26 +0100 thivol_d (oln/b/9_pnm_write3 1.1.1.13 600)
@@ -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
@@ -46,9 +46,13 @@
       | pnm_writer3d (Any) |
       `-------------------*/
-      // Only PnmRaw images can store more than one 2d image. The
-      // format is simple: each slice is stored as a bi-dimensional
-      // image.
+      /*! \class pnm_writer<WritePnmRaw, 3, P, I>
+      **
+      ** Specialized version for image 3d.
+      ** Only PnmRaw images can store more than one 2d image. The
+      ** format is simple: each slice is stored as a bi-dimensional
+      ** image.
+      */
template <pnm_type P, class I>
       struct pnm_writer<WritePnmRaw, 3, P, I>
@@ -69,6 +73,8 @@
      return writer_2d::knows_ext(ext);
    }
+	/// Write \a im on \a out, then return true.
+	
    static bool
    write(std::ostream& out, const I& im)
    {
Index: olena/oln/io/pnm_write.hh
--- olena/oln/io/pnm_write.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/b/15_pnm_write. 1.8.1.13 600)
+++ olena/oln/io/pnm_write.hh Mon, 15 Mar 2004 13:34:40 +0100 thivol_d (oln/b/15_pnm_write. 1.8.1.13 600)
@@ -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
@@ -41,6 +41,11 @@
       | default pnm_writer |
       `-------------------*/
+      /*! \class pnm_write
+      **
+      ** Default version.
+      */
+      
       template <writer_id W, unsigned Dim, pnm_type V, class I>
       struct pnm_writer
       {
Index: olena/oln/io/pnm_common.hh
--- olena/oln/io/pnm_common.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/t/40_pnm_common 1.4 600)
+++ olena/oln/io/pnm_common.hh Mon, 15 Mar 2004 19:00:49 +0100 thivol_d (oln/t/40_pnm_common 1.4 600)
@@ -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
@@ -66,6 +66,14 @@
       // Return the pnm type associated to an image type
       // FIXME: this could be done by using labels images
       // eg: read(binary_image_with_dim<2>& ima) { // ... }
+      
+      /*! \class get_pnm_type
+      **
+      ** A metaswitch that return the pnm type associated to an image type.
+      **
+      ** \todo FIXME: this could be done by using labels images
+      ** eg: read(binary_image_with_dim<2>& ima) { // ... }
+      */
       template <class I>
       struct get_pnm_type
       {
Index: olena/oln/io/stream_wrapper.hh
--- olena/oln/io/stream_wrapper.hh Mon, 15 Mar 2004 19:40:09 +0100 odou_s (oln/t/43_stream_wra 1.3.1.2 600)
+++ olena/oln/io/stream_wrapper.hh Mon, 15 Mar 2004 19:48:41 +0100 thivol_d (oln/t/43_stream_wra 1.3.1.2 600)
@@ -52,6 +52,16 @@
    	       StreamGz   = 2,
    	       StreamAny  = 2 };
+      /*! \class stream_wrapper
+      **
+      ** Default version, if you instantiate one, all the 
+      ** operations on the stream will fail
+      **
+      ** \see stream_wrapper<StreamFile>
+      **
+      ** \see stream_wrapper<StreamGz>
+      **
+      */
       template< stream_id W >
       struct stream_wrapper
       {
Index: olena/oln/io/pnm_read_data.hh
--- olena/oln/io/pnm_read_data.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/u/9_pnm_read_d 1.5 600)
+++ olena/oln/io/pnm_read_data.hh Mon, 15 Mar 2004 13:34:05 +0100 thivol_d (oln/u/9_pnm_read_d 1.5 600)
@@ -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
@@ -40,6 +40,12 @@
namespace internal {
+      
+      /*! \class pnm_read_data
+      **
+      ** Default version.
+      */
+      
       template<pnm_type V, reader_id R>
       struct pnm_read_data
       {
@@ -55,6 +61,14 @@
       | pnm read data binary |
       `---------------------*/
+      /*! \class pnm_read_data<PnmBinary, ReadPnmPlain>
+      **
+      ** Specialized version for extracting pnm binary 2d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+
       template <>
       struct pnm_read_data<PnmBinary, ReadPnmPlain>
       {
@@ -79,6 +93,12 @@
    }
       };
+      /*! \class pnm_read_data<PnmBinary, ReadPnmRaw>
+      **
+      ** Specialized version for extracting pnm binary 2d image
+      ** in raw file.
+      */
+      
       template <>
       struct pnm_read_data<PnmBinary, ReadPnmRaw>
       {
@@ -112,6 +132,15 @@
       | pnm read data integer |
       `----------------------*/
+      /*! \class pnm_read_data<PnmInteger, ReadPnmPlain>
+      **
+      ** Specialized version for extracting pnm integer 2d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
+      
       template <>
       struct pnm_read_data<PnmInteger, ReadPnmPlain>
       {
@@ -132,6 +161,15 @@
    }
       };
+          
+      /*! \class pnm_read_data<PnmInteger, ReadPnmRaw>
+      **
+      ** Specialized version for extracting pnm integer 2d image
+      ** in raw file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_read_data<PnmInteger, ReadPnmRaw>
       {
@@ -165,6 +203,15 @@
       | pnm read data vectorial |
       `------------------------*/
+          
+      /*! \class pnm_read_data<PnmVectorial, ReadPnmPlain>
+      **
+      ** Specialized version for extracting pnm vectorial 2d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_read_data<PnmVectorial, ReadPnmPlain>
       {
@@ -186,6 +233,15 @@
    }
       };
+          
+      /*! \class pnm_read_data<PnmInteger, ReadPnmRaw>
+      **
+      ** Specialized version for extracting pnm integer 2d image
+      ** in raw file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_read_data<PnmVectorial, ReadPnmRaw>
       {
Index: olena/oln/io/pnm_write_data.hh
--- olena/oln/io/pnm_write_data.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/u/10_pnm_write_ 1.6 600)
+++ olena/oln/io/pnm_write_data.hh Mon, 15 Mar 2004 13:49:03 +0100 thivol_d (oln/u/10_pnm_write_ 1.6 600)
@@ -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
@@ -40,6 +40,12 @@
namespace internal {
+      
+      /*! \class pnm_write_data
+      ** 
+      ** Default version
+      */
+      
       template<pnm_type V, writer_id R>
       struct pnm_write_data
       {
@@ -55,6 +61,15 @@
       | pnm write data binary |
       `----------------------*/
+             
+      /*! \class pnm_write_data<PnmBinary, WritePnmPlain>
+      **
+      ** Specialized version for writing pnm binary 3d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+
       template <>
       struct pnm_write_data<PnmBinary, WritePnmPlain>
       {
@@ -82,6 +97,14 @@
    }
       };
+      /*! \class pnm_write_data<PnmBinary, WritePnmRaw>
+      **
+      ** Specialized version for writing pnm binary 3d image
+      ** in raw file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+
       template <>
       struct pnm_write_data<PnmBinary, WritePnmRaw>
       {
@@ -121,6 +144,14 @@
       | pnm write data integer |
       `-----------------------*/
+      /*! \class pnm_write_data<PnmInteger, WritePnmPlain>
+      **
+      ** Specialized version for writing pnm integer 3d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */     
+      
       template <>
       struct pnm_write_data<PnmInteger, WritePnmPlain>
       {
@@ -148,6 +179,14 @@
    }
       };
+      /*! \class pnm_write_data<PnmInteger, WritePnmRaw>
+      **
+      ** Specialized version for writing pnm integer 3d image
+      ** in raw file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_write_data<PnmInteger, WritePnmRaw>
       {
@@ -179,6 +218,14 @@
       | pnm write data vectorial |
       `-------------------------*/
+      /*! \class pnm_write_data<PnmVectorial, WritePnmPlain>
+      **
+      ** Specialized version for writing pnm vectorial 3d image
+      ** in plain file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_write_data<PnmVectorial, WritePnmPlain>
       {
@@ -209,6 +256,14 @@
    }
       };
+      /*! \class pnm_write_data<PnmVectorial, WritePnmRaw>
+      **
+      ** Specialized version for writing pnm vectorial 3d image
+      ** in raw file.
+      **
+      ** \todo FIXME: implement an iterator over data
+      */
+      
       template <>
       struct pnm_write_data<PnmVectorial, WritePnmRaw>
       {
Index: olena/oln/io/pnm_read_2d.hh
--- olena/oln/io/pnm_read_2d.hh Thu, 07 Aug 2003 02:37:23 +0200 burrus_n (oln/u/43_pnm_read_2 1.4 600)
+++ olena/oln/io/pnm_read_2d.hh Mon, 15 Mar 2004 13:35:15 +0100 thivol_d (oln/u/43_pnm_read_2 1.4 600)
@@ -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
@@ -43,6 +43,12 @@
       | pnm_read_header2d |
       `------------------*/
+      /*! \brief Return true if the headers from \a s are valid,
+      ** false otherwise.
+      **
+      ** \todo FIXME: should be in a .cc file ?
+      */
+
       // FIXME: should be in a .cc file ?
       static bool 
       pnm_read_header2d(std::istream& s, char type, pnm2d_info& info)
@@ -80,6 +86,12 @@
       | pnm_reader (Binary) |
       `--------------------*/
+      
+      /*! \class pnm_reader<R, 2, PnmBinary, I>
+      **
+      ** Specialized version for PnmBinary (pbm image format).
+      */
+
       template <reader_id R, class I>
       struct pnm_reader<R, 2, PnmBinary, I>
       {
@@ -100,6 +112,10 @@
      return ext == "pbm";
    }
+	/*! \brief Initialize im and return true if the headers from \a in are valid, 
+	** return false otherwise.
+	*/
+	
    static bool
    read(std::istream& in, I& im)
    {
@@ -118,6 +134,11 @@
       | pnm_reader (Integer) |
       `---------------------*/
+      /*! \class pnm_reader<R, 2, PnmInteger, I>
+      **
+      ** Specialized version for PnmInteger (pgm image format).
+      */
+      
       template <reader_id R, class I>
       struct pnm_reader<R, 2, PnmInteger, I>
       {
@@ -138,6 +159,11 @@
      return ext == "pgm";
    }
+	/*! \brief Initialize \a im and return true if \a in is a valid pgm file stream,
+	** return false otherwise.
+	*/
+
+	
    static bool
    read(std::istream& in, I& im)
    {
@@ -161,6 +187,11 @@
       | pnm_reader (Vectorial) |
       `-----------------------*/
+      /*! \brief class pnm_reader<R, 2, PnmVectorial, I>
+      **
+      ** Specialized version for pnm_reader<R, 2, PnmVectorial, I> (ppm image format).
+      */
+
       template <reader_id R, class I>
       struct pnm_reader<R, 2, PnmVectorial, I>
       {
@@ -181,6 +212,10 @@
      return ext == "ppm";
    }
+	/*! \brief Initialize \a im and return true if \a in is a valid ppm file stream,
+	** return false otherwise.
+	*/
+	
    static bool
    read(std::istream& in, I& im)
    {
Index: olena/oln/io/pnm_write_2d.hh
--- olena/oln/io/pnm_write_2d.hh Mon, 03 Nov 2003 21:57:43 +0100 burrus_n (oln/u/44_pnm_write_ 1.5 600)
+++ olena/oln/io/pnm_write_2d.hh Mon, 15 Mar 2004 13:43:51 +0100 thivol_d (oln/u/44_pnm_write_ 1.5 600)
@@ -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
@@ -45,6 +45,11 @@
       | pnm_write_header2d |
       `------------------*/
+      /*! \brief Write headers in \a s output file, then return true.
+      **
+      ** \todo FIXME: should be in a .cc file ?
+      */
+      
       // FIXME: should be in a .cc file ?
       static bool 
       pnm_write_header2d(std::ostream& s, char type, const pnm2d_info& info)
@@ -62,6 +67,11 @@
       | pnm_writer (Binary) |
       `--------------------*/
+      /*! \class pnm_writer<W, 2, PnmBinary, I>
+      **
+      ** Specialized version for pbm images.
+      */
+      
       template <writer_id W, class I>
       struct pnm_writer<W, 2, PnmBinary, I>
       {
@@ -82,6 +92,10 @@
      return ext == "pbm";
    }
+	/*! \brief write \a im on \a out according to the pbm format,
+	** then return true.
+	*/
+	
    static bool
    write(std::ostream& out, const I& im)
    {
@@ -103,6 +117,11 @@
       | pnm_writer (Integer) |
       `---------------------*/
+      /*! \class pnm_writer<W, 2, PnmInteger, I>
+      **
+      ** Specialized version for pgm images.
+      */
+      
       template <writer_id W, class I>
       struct pnm_writer<W, 2, PnmInteger, I>
       {
@@ -123,6 +142,10 @@
      return ext == "pgm";
    }
+	/*! \brief Write \a im on \a out according to the pgm format, 
+	** then return true.
+	*/
+	
    static bool
    write(std::ostream& out, const I& im)
    {
@@ -147,6 +170,11 @@
       | pnm_writer (Vectorial) |
       `-----------------------*/
+      /*! \class pnm_writer<W, 2, PnmVectorial, I>
+      **
+      ** Specialized version for ppm images.
+      */
+      
       template <writer_id W, class I>
       struct pnm_writer<W, 2, PnmVectorial, I>
       {
@@ -167,6 +195,10 @@
      return ext == "ppm";
    }
+	/*! \brief Write \a im on \a out according to the ppm format,
+	** then return true.
+	*/
+		
    static bool
    write(std::ostream& out, const I& im)
    {
-- 
Damien Thivolle
damien.thivolle@lrde.epita.fr

    