Improve docs of Fl_Image and related classes (#431)

Clarifications as discussed since April 15, 2022 07:00 UTC (see GitHub
issue #431).

4 files changed, 33 insertions, 27 deletions

diff --git a/FL/Fl_Image.H b/FL/Fl_Image.H
index 34c545ea9..038384991 100644
--- a/FL/Fl_Image.H
+++ b/FL/Fl_Image.H
@@ -54,8 +54,8 @@ enum Fl_RGB_Scaling {
       returned by w() and h(). These values are equal to data_w() and data_h() when
       the image is created and can be changed by the scale() member function.
 
-  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.
+  Since the Fl_Image class does not support image drawing by itself, calling the
+  Fl_Image::draw() method results in a box with an X in it being drawn instead.
 */
 class FL_EXPORT Fl_Image {
   friend class Fl_Graphics_Driver;
@@ -239,7 +239,7 @@ public:
   /**
     Creates a copy of the image in the same size.
 
-    The copied image should be released when you are done with it.
+    The new image should be released when you are done with it.
 
     This does exactly the same as 'Fl_Image::copy(int W, int H) const' where
     \p W and \p H are the width and height of the source image, respectively.
diff --git a/FL/Fl_Shared_Image.H b/FL/Fl_Shared_Image.H
index 88a3050be..07551b70e 100644
--- a/FL/Fl_Shared_Image.H
+++ b/FL/Fl_Shared_Image.H
@@ -176,7 +176,7 @@ public:
 
     \note The internal image (pointer) is protected for good reasons, e.g.
       to prevent access to the image so it can't be modified by user code.
-      \b DO \b NOT cast away the 'const' to modify the image.
+      \b DO \b NOT cast away the 'const' attribute to modify the image.
 
     User code should rarely need this method. Use with caution.
 
diff --git a/src/Fl_GIF_Image.cxx b/src/Fl_GIF_Image.cxx
index b6b51fb45..67f1014ba 100644
--- a/src/Fl_GIF_Image.cxx
+++ b/src/Fl_GIF_Image.cxx
@@ -105,7 +105,7 @@ static int gif_error(Fl_Image_Reader &rdr, int line, uchar *Image) {
 /**
   This constructor loads a GIF image from the given file.
 
-  IF a GIF image is animated, Fl_GIF_Image will only read and display the
+  If a GIF image is animated, Fl_GIF_Image will only read and display the
   first frame of the animation.
 
   The destructor frees all memory and server resources that are used by
@@ -140,7 +140,7 @@ Fl_GIF_Image::Fl_GIF_Image(const char *filename) :
   \p imagename can be NULL. If a name is given, the image is added to the list of
   shared images and will be available by that name.
 
-  IF a GIF image is animated, Fl_GIF_Image will only read and display the
+  If a GIF image is animated, Fl_GIF_Image will only read and display the
   first frame of the animation.
 
   The destructor frees all memory and server resources that are used by
diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx
index 051e7fc6f..a4dd6d921 100644
--- a/src/Fl_Image.cxx
+++ b/src/Fl_Image.cxx
@@ -78,20 +78,27 @@ void Fl_Image::draw_empty(int X, int Y) {
 /**
   Creates a resized copy of the image.
 
-  The copied image should be released when you are done with it.
+  The new image should be released when you are done with it.
 
   Note: since FLTK 1.4.0 you can use Fl_Image::release() for all types
   of images (i.e. all subclasses of Fl_Image) instead of operator \em delete
   for Fl_Image's and Fl_Image::release() for Fl_Shared_Image's.
 
-  The copied image data will be converted to the requested size. RGB images
+  The new image data will be converted to the requested size. RGB images
   are resized using the algorithm set by Fl_Image::RGB_scaling().
 
-  For the copied image the following equations are true:
+  For the new image the following equations are true:
   - w() == data_w() == \p W
   - h() == data_h() == \p H
 
-  \param[in] W,H  Requested width and height of the copied image
+  Note: the returned image can be safely cast to the same image type as that
+  of the source image provided this type is one of Fl_RGB_Image, Fl_SVG_Image,
+  Fl_Pixmap, Fl_Bitmap, Fl_Tiled_Image, and Fl_Shared_Image.
+  Returned objects copied from images of other, derived, image classes belong
+  to the parent class appearing in this list. For example, the copy of an
+  Fl_GIF_Image is an object of class Fl_Pixmap.
+
+  \param[in] W,H  Requested width and height of the new image
 
   \note Since FLTK 1.4.0 this method is 'const'. If you derive your own class
     from Fl_Image or any subclass your overridden methods of 'Fl_Image::copy() const'
@@ -104,15 +111,17 @@ Fl_Image *Fl_Image::copy(int W, int H) const {
 }
 
 /**
-  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.
-
-  An internal copy is made of the original image before
-  changes are applied, to avoid modifying the original image.
+  The color_average() method averages the colors in the image with
+  the provided FLTK color value.
+
+  The first argument specifies the FLTK color to be used.
+
+  The second 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.
+
+  An internal copy is made of the original image data before changes are
+  applied, to avoid modifying the original image data in memory.
 */
 void Fl_Image::color_average(Fl_Color, float) {
 }
@@ -123,8 +132,8 @@ void Fl_Image::color_average(Fl_Color, float) {
   If the image contains an alpha channel (depth = 4),
   the alpha channel is preserved.
 
-  An internal copy is made of the original image data before
-  changes are applied, to avoid modifying the original image data.
+  An internal copy is made of the original image data before changes are
+  applied, to avoid modifying the original image data in memory.
 */
 void Fl_Image::desaturate() {
 }
@@ -143,19 +152,16 @@ Fl_Labeltype Fl_Image::define_FL_IMAGE_LABEL() {
   This method is 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.
+  \deprecated Please use Fl_Widget::image() or Fl_Widget::deimage() instead.
 */
 void Fl_Image::label(Fl_Widget* widget) {
   widget->image(this);
 }
 
 /**
-  This method is an obsolete way to set the image attribute of a widget
-  or menu item.
+  This method is an obsolete way to set the image attribute of a menu item.
 
-  Use the image() or deimage() methods of the Fl_Widget and Fl_Menu_Item
-  classes instead.
+  \deprecated Please use Fl_Menu_Item::image() instead.
 */
 void Fl_Image::label(Fl_Menu_Item* m) {
   m->label(FL_IMAGE_LABEL, (const char*)this);