Doxygen Documentation WP5 Done, WP6 half finished so that all Fl_Image class hierarchy is up-to-date. Also completed the documentation of the useful Fl_Shared_Image.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6241 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

23 files changed, 325 insertions, 69 deletions

diff --git a/FL/Fl_BMP_Image.H b/FL/Fl_BMP_Image.H
index 20aba3d05..0692aa669 100644
--- a/FL/Fl_BMP_Image.H
+++ b/FL/Fl_BMP_Image.H
@@ -29,6 +29,10 @@
 #define Fl_BMP_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_BMP_Image class supports loading, caching,
+  and drawing of Windows Bitmap (BMP) image files.
+*/
 class FL_EXPORT Fl_BMP_Image : public Fl_RGB_Image {
 
   public:
diff --git a/FL/Fl_Bitmap.H b/FL/Fl_Bitmap.H
index 187fdf8ad..2429d246a 100644
--- a/FL/Fl_Bitmap.H
+++ b/FL/Fl_Bitmap.H
@@ -32,6 +32,10 @@
 class Fl_Widget;
 struct Fl_Menu_Item;
 
+/**
+  The Fl_Bitmap class supports caching and drawing of mono-color
+  (bitmap) images. Images are drawn using the current color.
+*/
 class FL_EXPORT Fl_Bitmap : public Fl_Image {
   public:
 
@@ -42,9 +46,10 @@ class FL_EXPORT Fl_Bitmap : public Fl_Image {
 #else
   unsigned id; // for internal use
 #endif // __APPLE__ || WIN32
-  
+  /** The constructors create a new bitmap from the specified bitmap data */
   Fl_Bitmap(const uchar *bits, int W, int H) :
     Fl_Image(W,H,0), array(bits), alloc_array(0), id(0) {data((const char **)&array, 1);}
+  /** The constructors create a new bitmap from the specified bitmap data */
   Fl_Bitmap(const char *bits, int W, int H) :
     Fl_Image(W,H,0), array((const uchar *)bits), alloc_array(0), id(0) {data((const char **)&array, 1);}
   virtual ~Fl_Bitmap();
diff --git a/FL/Fl_GIF_Image.H b/FL/Fl_GIF_Image.H
index 94bf067b4..b231d5037 100644
--- a/FL/Fl_GIF_Image.H
+++ b/FL/Fl_GIF_Image.H
@@ -29,6 +29,11 @@
 #define Fl_GIF_Image_H
 #  include "Fl_Pixmap.H"
 
+/**
+  The Fl_GIF_Image class supports loading, caching,
+  and drawing of Compuserve GIF<SUP>SM</SUP> images. The class
+  loads the first image and supports transparency.
+*/
 class FL_EXPORT Fl_GIF_Image : public Fl_Pixmap {
 
   public:
diff --git a/FL/Fl_Image.H b/FL/Fl_Image.H
index e38b3b17c..1a85f07f8 100644
--- a/FL/Fl_Image.H
+++ b/FL/Fl_Image.H
@@ -34,6 +34,17 @@ class Fl_Widget;
 struct Fl_Menu_Item;
 struct Fl_Label;
 
+/**
+  Fl_Image is the base class used for caching and
+  drawing all kinds of images in FLTK. This class keeps track of
+  common image data such as the pixels, colormap, width, height,
+  and depth. Virtual methods are used to provide type-specific
+  image handling.</P>
+  
+  <P>Since the Fl_Image class does not support image
+  drawing by itself, calling the draw() method results in
+  a box with an X in it being drawn instead.
+*/
 class FL_EXPORT Fl_Image {
   int w_, h_, d_, ld_, count_;
   const char * const *data_;
@@ -44,10 +55,34 @@ class FL_EXPORT Fl_Image {
 
   protected:
 
+  /**
+    The first form of the w() method returns the current
+    image width in pixels.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image width.
+  */
   void w(int W) {w_ = W;}
+  /**
+    The first form of the h() method returns the current
+    image height in pixels.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image height.
+  */
   void h(int H) {h_ = H;}
+  /**
+    The first form of the d() method returns the current
+    image depth. The return value will be 0 for bitmaps, 1 for
+    pixmaps, and 1 to 4 for color images.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image depth.
+  */
   void d(int D) {d_ = D;}
+  /**    See int ld()  */
   void ld(int LD) {ld_ = LD;}
+  /**    See const char * const *data()  */
   void data(const char * const *p, int c) {data_ = p; count_ = c;}
   void draw_empty(int X, int Y);
 
@@ -56,27 +91,99 @@ class FL_EXPORT Fl_Image {
 
   public:
 
+  /** See void Fl_Image::w(int) */
   int w() const {return w_;}
+  /** See void Fl_Image::h(int) */
   int h() const {return h_;}
+  /**
+    The first form of the d() method returns the current
+    image depth. The return value will be 0 for bitmaps, 1 for
+    pixmaps, and 1 to 4 for color images.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image depth.
+  */
   int d() const {return d_;}
+  /**
+    The first form of the ld() method returns the current
+    line data size in bytes. Line data is extra data that is included
+    after each line of color image data and is normally not present.</P>
+    
+    <P>The second form is a protected method that sets the current
+    line data size in bytes.
+  */
   int ld() const {return ld_;}
+  /**
+    The count() method returns the number of data values
+    associated with the image. The value will be 0 for images with
+    no associated data, 1 for bitmap and color images, and greater
+    than 2 for pixmap images.
+  */
   int count() const {return count_;}
+  /**
+    The first form of the data() method returns a
+    pointer to the current image data array. Use the
+    count() method to find the size of the data array.</P>
+    
+    <P>The second form is a protected method that sets the current
+    array pointer and count of pointers in the array.
+  */
   const char * const *data() const {return data_;}
   
+  /**
+    The constructor creates an empty image with the specified
+    width, height, and depth. The width and height are in pixels.
+    The depth is 0 for bitmaps, 1 for pixmap (colormap) images, and
+    1 to 4 for color images.
+  */
   Fl_Image(int W, int H, int D) {w_ = W; h_ = H; d_ = D; ld_ = 0; count_ = 0; data_ = 0;}
   virtual ~Fl_Image();
   virtual Fl_Image *copy(int W, int H);
+  /**
+    The copy() method creates a copy of the specified
+    image. If the width and height are provided, the image is
+    resized to the specified size. The image should be deleted (or in
+    the case of Fl_Shared_Image, released) when you are done
+    with it.
+  */
   Fl_Image *copy() { return copy(w(), h()); }
   virtual void color_average(Fl_Color c, float i);
+  /**
+    The inactive() method calls
+    color_average(FL_BACKGROUND_COLOR, 0.33f) to produce 
+    an image that appears grayed out. <I>This method does not 
+    alter the original image data.</I>
+  */
   void inactive() { color_average(FL_GRAY, .33f); }
   virtual void desaturate();
   virtual void label(Fl_Widget*w);
   virtual void label(Fl_Menu_Item*m);
-  virtual void draw(int X, int Y, int W, int H, int cx=0, int cy=0);
-  void draw(int X, int Y) {draw(X, Y, w(), h(), 0, 0);}
+  /**
+    The draw() methods draw the image. This form specifies
+    a bounding box for the image, with the origin
+    (upper-lefthand corner) of the image offset by the cx
+    and cy arguments.
+  */
+  virtual void draw(int X, int Y, int W, int H, int cx=0, int cy=0); // platform dependent
+  /**
+    The draw() methods draw the image. This form
+    specifies the upper-lefthand corner of the image
+  */
+  void draw(int X, int Y) {draw(X, Y, w(), h(), 0, 0);} // platform dependent
   virtual void uncache();
 };
 
+/**
+  The Fl_RGB_Image class supports caching and drawing
+  of full-color images with 1 to 4 channels of color information.
+  Images with an even number of channels are assumed to contain
+  alpha information, which is used to blend the image with the
+  contents of the screen.</P>
+  
+  <P>Fl_RGB_Image is defined in
+  &lt;FL/Fl_Image.H&gt;, however for compatibility reasons
+  &lt;FL/Fl_RGB_Image.H&gt; should be included.
+*/
 class FL_EXPORT Fl_RGB_Image : public Fl_Image {
   public:
 
@@ -90,7 +197,7 @@ class FL_EXPORT Fl_RGB_Image : public Fl_Image {
   unsigned id; // for internal use
   unsigned mask; // for internal use (mask bitmap)
 #endif // __APPLE__ || WIN32
-
+/**  The constructor creates a new image from the specified data. */
   Fl_RGB_Image(const uchar *bits, int W, int H, int D=3, int LD=0) :
     Fl_Image(W,H,D), array(bits), alloc_array(0), id(0), mask(0) {data((const char **)&array, 1); ld(LD);}
   virtual ~Fl_RGB_Image();
diff --git a/FL/Fl_JPEG_Image.H b/FL/Fl_JPEG_Image.H
index 4cf1b20d0..3501f6491 100644
--- a/FL/Fl_JPEG_Image.H
+++ b/FL/Fl_JPEG_Image.H
@@ -29,6 +29,12 @@
 #define Fl_JPEG_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_JPEG_Image class supports loading, caching,
+  and drawing of Joint Photographic Experts Group (JPEG) File
+  Interchange Format (JFIF) images. The class supports grayscale
+  and color (RGB) JPEG image files.
+*/
 class FL_EXPORT Fl_JPEG_Image : public Fl_RGB_Image {
 
   public:
diff --git a/FL/Fl_PNG_Image.H b/FL/Fl_PNG_Image.H
index 86c01fdb1..1b30e7f35 100644
--- a/FL/Fl_PNG_Image.H
+++ b/FL/Fl_PNG_Image.H
@@ -29,6 +29,12 @@
 #define Fl_PNG_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_PNG_Image class supports loading, caching,
+  and drawing of Portable Network Graphics (PNG) image files. The
+  class loads colormapped and full-color images and handles color-
+  and alpha-based transparency.
+*/
 class FL_EXPORT Fl_PNG_Image : public Fl_RGB_Image {
 
   public:
diff --git a/FL/Fl_PNM_Image.H b/FL/Fl_PNM_Image.H
index a8ce4d2ec..bc4ecc279 100644
--- a/FL/Fl_PNM_Image.H
+++ b/FL/Fl_PNM_Image.H
@@ -29,6 +29,12 @@
 #define Fl_PNM_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_PNM_Image class supports loading, caching,
+  and drawing of Portable Anymap (PNM, PBM, PGM, PPM) image files. The class
+  loads bitmap, grayscale, and full-color images in both ASCII and
+  binary formats.
+*/
 class FL_EXPORT Fl_PNM_Image : public Fl_RGB_Image {
 
   public:
diff --git a/FL/Fl_Pixmap.H b/FL/Fl_Pixmap.H
index 2804ff7f9..be65a3288 100644
--- a/FL/Fl_Pixmap.H
+++ b/FL/Fl_Pixmap.H
@@ -37,6 +37,10 @@ struct Fl_Menu_Item;
 #    define explicit
 #  endif // __sgi && !_COMPILER_VERSION
 
+/**
+  The Fl_Pixmap class supports caching and drawing of colormap
+  (pixmap) images, including transparency.
+*/
 class FL_EXPORT Fl_Pixmap : public Fl_Image {
   void copy_data();
   void delete_data();
@@ -57,9 +61,13 @@ class FL_EXPORT Fl_Pixmap : public Fl_Image {
   unsigned mask; // for internal use (mask bitmap)
 #endif // __APPLE__ || WIN32
   
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(char * const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(uchar* const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(const char * const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(const uchar* const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
   virtual ~Fl_Pixmap();
   virtual Fl_Image *copy(int W, int H);
diff --git a/FL/Fl_Shared_Image.H b/FL/Fl_Shared_Image.H
index 0dd6f3cd8..6f766ece8 100644
--- a/FL/Fl_Shared_Image.H
+++ b/FL/Fl_Shared_Image.H
@@ -36,6 +36,13 @@ typedef Fl_Image *(*Fl_Shared_Handler)(const char *name, uchar *header,
                                        int headerlen);
 
 // Shared images class. 
+/**
+  This class supports caching, loading,
+  and drawing of image files. Most applications will also want to
+  link against the fltk_images library and call the
+  fl_register_images()
+  function to support standard image formats such as BMP, GIF, JPEG, and PNG.
+*/
 class FL_EXPORT Fl_Shared_Image : public Fl_Image {
   protected:
 
@@ -62,8 +69,9 @@ class FL_EXPORT Fl_Shared_Image : public Fl_Image {
   void update();
 
   public:
-
+  /** Returns the filename of the shared image */
   const char	*name() { return name_; }
+  /** Returns the number of references of this shared image. When reference is below 1, the image is deleted. */
   int		refcount() { return refcount_; }
   void		release();
   void		reload();
diff --git a/FL/Fl_XBM_Image.H b/FL/Fl_XBM_Image.H
index 955210198..e0470b1d7 100644
--- a/FL/Fl_XBM_Image.H
+++ b/FL/Fl_XBM_Image.H
@@ -29,6 +29,10 @@
 #define Fl_XBM_Image_H
 #  include "Fl_Bitmap.H"
 
+/**
+  The Fl_XBM_Image class supports loading, caching,
+  and drawing of X Bitmap (XBM) bitmap files.
+*/
 class FL_EXPORT Fl_XBM_Image : public Fl_Bitmap {
 
   public:
diff --git a/FL/Fl_XPM_Image.H b/FL/Fl_XPM_Image.H
index 9d0e7bab0..554abfcc9 100644
--- a/FL/Fl_XPM_Image.H
+++ b/FL/Fl_XPM_Image.H
@@ -29,6 +29,10 @@
 #define Fl_XPM_Image_H
 #  include "Fl_Pixmap.H"
 
+/**
+  The Fl_XPM_Image class supports loading, caching,
+  and drawing of X Pixmap (XPM) images, including transparency.
+*/
 class FL_EXPORT Fl_XPM_Image : public Fl_Pixmap {
 
   public:
diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt
index df38628ab..aac1ac06f 100644
--- a/documentation/todo_filelist_doc.txt
+++ b/documentation/todo_filelist_doc.txt
@@ -13,7 +13,7 @@ In Progress Work List (add your WP and name here):
   - WP2  (Fabien) DONE
   - WP3  (engelsman)
   - WP4  (Fabien) DONE
-  - WP5  (Fabien)
+  - WP5  (Fabien) DONE
   - WP6  (Fabien)
   - WP7
   - WP8
diff --git a/src/Fl_BMP_Image.cxx b/src/Fl_BMP_Image.cxx
index c59504ba6..4c5e31da6 100644
--- a/src/Fl_BMP_Image.cxx
+++ b/src/Fl_BMP_Image.cxx
@@ -59,12 +59,15 @@
 static int		read_long(FILE *fp);
 static unsigned short	read_word(FILE *fp);
 static unsigned int	read_dword(FILE *fp);
+/** \fn Fl_BMP_Image::~Fl_BMP_Image()
+*/
 
 
-//
-// 'Fl_BMP_Image::Fl_BMP_Image()' - Load a BMP image file.
-//
-
+/** 
+  The constructor loads the named BMP image from the given bmp filename.  
+  <P>The inherited destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_BMP_Image::Fl_BMP_Image(const char *bmp) // I - File to read
   : Fl_RGB_Image(0,0,0) {
   FILE		*fp;		// File pointer
diff --git a/src/Fl_Bitmap.cxx b/src/Fl_Bitmap.cxx
index ae49d934e..c4b32cd0a 100644
--- a/src/Fl_Bitmap.cxx
+++ b/src/Fl_Bitmap.cxx
@@ -25,6 +25,12 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn Fl_Bitmap::Fl_Bitmap(const char *array, int W, int H)
+  The constructors create a new bitmap from the specified bitmap data.*/
+
+/** \fn Fl_Bitmap::Fl_Bitmap(const unsigned char *array, int W, int H)
+  The constructors create a new bitmap from the specified bitmap data.*/
+
 #include <FL/Fl.H>
 #include <FL/x.H>
 #include <FL/fl_draw.H>
@@ -414,6 +420,10 @@ void Fl_Bitmap::draw(int XP, int YP, int WP, int HP, int cx, int cy) {
 #endif
 }
 
+/**
+  The destructor free all memory and server resources that are used by
+  the bitmap.
+*/
 Fl_Bitmap::~Fl_Bitmap() {
   uncache();
   if (alloc_array) delete[] (uchar *)array;
diff --git a/src/Fl_GIF_Image.cxx b/src/Fl_GIF_Image.cxx
index 395ace3cb..ee5e726da 100644
--- a/src/Fl_GIF_Image.cxx
+++ b/src/Fl_GIF_Image.cxx
@@ -79,6 +79,11 @@ typedef unsigned char uchar;
 #define NEXTBYTE (uchar)getc(GifFile)
 #define GETSHORT(var) var = NEXTBYTE; var += NEXTBYTE << 8
 
+/**  
+  The constructor loads the named GIF image.
+  <P>The inherited destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_GIF_Image::Fl_GIF_Image(const char *infname) : Fl_Pixmap((char *const*)0) {
   FILE *GifFile;	// File to read
   char **new_data;	// Data array
diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx
index 553000fa8..6cd9514bd 100644
--- a/src/Fl_Image.cxx
+++ b/src/Fl_Image.cxx
@@ -43,9 +43,18 @@ void fl_restore_clip(); // from fl_rect.cxx
 // Base image class...
 //
 
+/**
+  The destructor is a virtual method that frees all memory used
+  by the image.
+*/
 Fl_Image::~Fl_Image() {
 }
 
+/**
+  If the image has been cached for display, delete the cache
+  data. This allows you to change the data used for the image and
+  then redraw it without recreating an image object.
+*/
 void Fl_Image::uncache() {
 }
 
@@ -53,6 +62,11 @@ void Fl_Image::draw(int XP, int YP, int, int, int, int) {
   draw_empty(XP, YP);
 }
 
+/**
+  The protected method draw_empty() draws a box with
+  an X in it. It can be used to draw any image that lacks image
+  data.
+*/
 void Fl_Image::draw_empty(int X, int Y) {
   if (w() > 0 && h() > 0) {
     fl_color(FL_FOREGROUND_COLOR);
@@ -62,20 +76,56 @@ void Fl_Image::draw_empty(int X, int Y) {
   }
 }
 
+/**
+  The copy() method creates a copy of the specified
+  image. If the width and height are provided, the image is
+  resized to the specified size. The image should be deleted (or in
+  the case of Fl_Shared_Image, released) when you are done
+  with it.
+*/
 Fl_Image *Fl_Image::copy(int W, int H) {
   return new Fl_Image(W, H, d());
 }
 
+/**
+  The color_average() method averages the colors in
+  the image with the FLTK color value c. The i
+  argument specifies the amount of the original image to combine
+  with the color, so a value of 1.0 results in no color blend, and
+  a value of 0.0 results in a constant image of the specified
+  color. <I>The original image data is not altered by this
+  method.</I>
+*/
 void Fl_Image::color_average(Fl_Color, float) {
 }
 
+/**
+  The desaturate() method converts an image to
+  grayscale. If the image contains an alpha channel (depth = 4),
+  the alpha channel is preserved. <I>This method does not alter
+  the original image data.</I>
+*/
 void Fl_Image::desaturate() {
 }
 
+/**
+  The label() methods are an obsolete way to set the
+  image attribute of a widget or menu item. Use the
+  image() or deimage() methods of the
+  Fl_Widget and Fl_Menu_Item classes
+  instead.
+*/
 void Fl_Image::label(Fl_Widget* widget) {
   widget->image(this);
 }
 
+/**
+  The label() methods are an obsolete way to set the
+  image attribute of a widget or menu item. Use the
+  image() or deimage() methods of the
+  Fl_Widget and Fl_Menu_Item classes
+  instead.
+*/
 void Fl_Image::label(Fl_Menu_Item* m) {
   Fl::set_labeltype(_FL_IMAGE_LABEL, labeltype, measure);
   m->label(_FL_IMAGE_LABEL, (const char*)this);
@@ -122,7 +172,7 @@ Fl_Image::measure(const Fl_Label *lo,		// I - Label
 //
 // RGB image class...
 //
-
+/**  The destructor free all memory and server resources that are used by  the image. */
 Fl_RGB_Image::~Fl_RGB_Image() {
   uncache();
   if (alloc_array) delete[] (uchar *)array;
diff --git a/src/Fl_JPEG_Image.cxx b/src/Fl_JPEG_Image.cxx
index 13889000a..63c09261e 100644
--- a/src/Fl_JPEG_Image.cxx
+++ b/src/Fl_JPEG_Image.cxx
@@ -88,10 +88,10 @@ extern "C" {
 #endif // HAVE_LIBJPEG
 
 
-//
-// 'Fl_JPEG_Image::Fl_JPEG_Image()' - Load a JPEG image file.
-//
-
+/**
+  The constructor loads the JPEG image from the given jpeg filename.
+  <P>The inherited destructor free all memory and server resources that are used by  the image.
+*/
 Fl_JPEG_Image::Fl_JPEG_Image(const char *jpeg)	// I - File to load
   : Fl_RGB_Image(0,0,0) {
 #ifdef HAVE_LIBJPEG
diff --git a/src/Fl_PNG_Image.cxx b/src/Fl_PNG_Image.cxx
index 99011d088..547601c7b 100644
--- a/src/Fl_PNG_Image.cxx
+++ b/src/Fl_PNG_Image.cxx
@@ -26,6 +26,7 @@
 //     http://www.fltk.org/str.php
 //
 // Contents:
+
 //
 //   Fl_PNG_Image::Fl_PNG_Image() - Load a PNG image file.
 //
@@ -54,10 +55,11 @@ extern "C"
 }
 
 
-//
-// 'Fl_PNG_Image::Fl_PNG_Image()' - Load a PNG image file.
-//
-
+/**
+  The constructor loads the named PNG image from the given png filename.
+  <P>The destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_PNG_Image::Fl_PNG_Image(const char *png) // I - File to read
   : Fl_RGB_Image(0,0,0) {
 #if defined(HAVE_LIBPNG) && defined(HAVE_LIBZ)
diff --git a/src/Fl_PNM_Image.cxx b/src/Fl_PNM_Image.cxx
index d7468b2e1..168f570f5 100644
--- a/src/Fl_PNM_Image.cxx
+++ b/src/Fl_PNM_Image.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 // Contents:
+
 //
 //   Fl_PNM_Image::Fl_PNM_Image() - Load a PNM image...
 //
@@ -45,6 +46,11 @@
 // 'Fl_PNM_Image::Fl_PNM_Image()' - Load a PNM image...
 //
 
+/** 
+  The constructor loads the named PNM image. 
+  <P>The inherited destructor free all memory and server resources that are used by the image.
+*/
+
 Fl_PNM_Image::Fl_PNM_Image(const char *name)	// I - File to read
   : Fl_RGB_Image(0,0,0) {
   FILE		*fp;		// File pointer
diff --git a/src/Fl_Pixmap.cxx b/src/Fl_Pixmap.cxx
index a3fad728a..6d24420d0 100644
--- a/src/Fl_Pixmap.cxx
+++ b/src/Fl_Pixmap.cxx
@@ -25,6 +25,15 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn Fl_Pixmap::Fl_Pixmap(const char **data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
+/** \fn Fl_Pixmap::Fl_Pixmap(const unsigned char * const *data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
+/** \fn Fl_Pixmap::Fl_Pixmap(const unsigned char **data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
 // Draws X pixmap data, keeping it stashed in a server pixmap so it
 // redraws fast.
 
@@ -169,6 +178,10 @@ void Fl_Pixmap::draw(int XP, int YP, int WP, int HP, int cx, int cy) {
 #endif
 }
 
+/**
+  The destructor free all memory and server resources that are used by
+  the pixmap.
+*/
 Fl_Pixmap::~Fl_Pixmap() {
   uncache();
   delete_data();
diff --git a/src/Fl_Shared_Image.cxx b/src/Fl_Shared_Image.cxx
index 2ed07eb00..083e12715 100644
--- a/src/Fl_Shared_Image.cxx
+++ b/src/Fl_Shared_Image.cxx
@@ -58,12 +58,11 @@ extern "C" {
 }
 
 
-// Static methods that really should be inline, but some WIN32 compilers
-// can't handle it...
+/** Returns the Fl_Shared_Image* array */
 Fl_Shared_Image **Fl_Shared_Image::images() {
   return images_;
 }
-
+/** Returns the total number of shared images in the array. */
 int Fl_Shared_Image::num_images() {
   return num_images_;
 }
@@ -86,10 +85,13 @@ Fl_Shared_Image::compare(Fl_Shared_Image **i0,		// I - First image
 }
 
 
-//
-// 'Fl_Shared_Image::Fl_Shared_Image()' - Basic constructor.
-//
-
+/** 
+  Creates an empty shared image.
+  The constructors create a new shared image record in the image cache.
+  
+  <P>The constructors are protected and cannot be used directly
+  from a program. Use the get() method instead.
+*/
 Fl_Shared_Image::Fl_Shared_Image() : Fl_Image(0,0,0) {
   name_        = 0;
   refcount_    = 1;
@@ -99,10 +101,13 @@ Fl_Shared_Image::Fl_Shared_Image() : Fl_Image(0,0,0) {
 }
 
 
-//
-// 'Fl_Shared_Image::Fl_Shared_Image()' - Add an image to the image cache.
-//
-
+/** 
+  Creates a shared image from its filename and its corresponding Fl_Image* img.
+  The constructors create a new shared image record in the image cache.
+  
+  <P>The constructors are protected and cannot be used directly
+  from a program. Use the get() method instead.
+*/
 Fl_Shared_Image::Fl_Shared_Image(const char *n,		// I - Filename
                                  Fl_Image   *img)	// I - Image
   : Fl_Image(0,0,0) {
@@ -165,11 +170,12 @@ Fl_Shared_Image::update() {
   }
 }
 
-
-//
-// 'Fl_Shared_Image::~Fl_Shared_Image()' - Destroy a shared image...
-//
-
+/**
+  The destructor free all memory and server resources that are
+  used by the image. The destructor is protected and cannot be
+  used directly from a program. Use the Fl_Shared_Image::release() method
+  instead.
+*/
 Fl_Shared_Image::~Fl_Shared_Image() {
   if (name_) delete[] (char *)name_;
   if (alloc_image_) delete image_;
@@ -177,11 +183,11 @@ Fl_Shared_Image::~Fl_Shared_Image() {
 
 
 //
-// 'Fl_Shared_Image::release()' - Release and possibly destroy a shared image.
-//
-
-void
-Fl_Shared_Image::release() {
+/** 
+  Releases and possibly destroys (if refcount <=0) a shared image. 
+  In the latter case, it will reorganize the shared image array so that no hole will occur.
+*/
+void Fl_Shared_Image::release() {
   int	i;	// Looping var...
 
   refcount_ --;
@@ -211,11 +217,8 @@ Fl_Shared_Image::release() {
 
 
 //
-// 'Fl_Shared_Image::reload()' - Reload the shared image...
-//
-
-void
-Fl_Shared_Image::reload() {
+/** Reloads the shared image from disk */
+void Fl_Shared_Image::reload() {
   // Load image from disk...
   int		i;		// Looping var
   FILE		*fp;		// File pointer
@@ -335,19 +338,15 @@ Fl_Shared_Image::draw(int X, int Y, int W, int H, int cx, int cy) {
 // 'Fl_Shared_Image::uncache()' - Uncache the shared image...
 //
 
-void
-Fl_Shared_Image::uncache()
+void Fl_Shared_Image::uncache()
 {
   if (image_) image_->uncache();
 }
 
 
-//
-// 'Fl_Shared_Image::find()' - Find a shared image...
-//
 
-Fl_Shared_Image *
-Fl_Shared_Image::find(const char *n, int W, int H) {
+/** Finds a shared image from its named and size specifications */
+Fl_Shared_Image* Fl_Shared_Image::find(const char *n, int W, int H) {
   Fl_Shared_Image	*key,		// Image key
 			**match;	// Matching image
 
@@ -374,12 +373,14 @@ Fl_Shared_Image::find(const char *n, int W, int H) {
 }
 
 
-//
-// 'Fl_Shared_Image::get()' - Get a shared image...
-//
-
-Fl_Shared_Image *
-Fl_Shared_Image::get(const char *n, int W, int H) {
+/** 
+  Gets a shared image, if it exists already ; it will return it.
+  If it does not exist or if it exist but with other size, 
+  then the existing image is deleted and replaced
+  by a new image from the n filename of the proper dimension.
+  If n is not a valid image filename, then get() will return NULL.
+*/
+Fl_Shared_Image* Fl_Shared_Image::get(const char *n, int W, int H) {
   Fl_Shared_Image	*temp;		// Image
 
   if ((temp = find(n, W, H)) != NULL) return temp;
@@ -404,12 +405,9 @@ Fl_Shared_Image::get(const char *n, int W, int H) {
 }
 
 
-//
-// 'Fl_Shared_Image::add_handler()' - Add a shared image handler.
-//
 
-void
-Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
+/** Adds a shared image handler, which is basically a test function for adding new formats */
+void Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
   int			i;		// Looping var...
   Fl_Shared_Handler	*temp;		// New image handler array...
 
@@ -437,12 +435,9 @@ Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
 }
 
 
-//
-// 'Fl_Shared_Image::remove_handler()' - Remove a shared image handler.
-//
 
-void
-Fl_Shared_Image::remove_handler(Fl_Shared_Handler f) {
+/** Removes a shared image handler */
+void Fl_Shared_Image::remove_handler(Fl_Shared_Handler f) {
   int	i;				// Looping var...
 
   // First see if the handler has been added...
diff --git a/src/Fl_XBM_Image.cxx b/src/Fl_XBM_Image.cxx
index d4d02d270..4406f7cef 100644
--- a/src/Fl_XBM_Image.cxx
+++ b/src/Fl_XBM_Image.cxx
@@ -44,6 +44,11 @@
 // 'Fl_XBM_Image::Fl_XBM_Image()' - Load an XBM file.
 //
 
+/**  
+  The constructor loads the named XBM file from the given name filename.
+  <P>The destructor free all memory and server resources that are used by 
+  the image.
+*/
 Fl_XBM_Image::Fl_XBM_Image(const char *name) : Fl_Bitmap((const char *)0,0,0) {
   FILE	*f;
   uchar	*ptr;
diff --git a/src/Fl_XPM_Image.cxx b/src/Fl_XPM_Image.cxx
index 09d5c0fbc..603e58b35 100644
--- a/src/Fl_XPM_Image.cxx
+++ b/src/Fl_XPM_Image.cxx
@@ -53,7 +53,11 @@ static int hexdigit(int x) {	// I - Hex digit...
 
 #define MAXSIZE 2048
 #define INITIALLINES 256
-
+/**
+  The constructor loads the XPM image from the name filename.
+  <P>The destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_XPM_Image::Fl_XPM_Image(const char *name) : Fl_Pixmap((char *const*)0) {
   FILE *f;