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

1 files changed, 44 insertions, 49 deletions

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...