added doxygen comments for undocumented features of Fl_File_Icon

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

FL/Fl_File_Icon.H

@@ -3,7 +3,7 @@
 //
 // Fl_File_Icon definitions.
 //
-// Copyright 1999-2005 by Michael Sweet.
+// Copyright 1999-2008 by Michael Sweet.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -42,7 +42,7 @@
 // Special color value for the icon color.
 //
 
-#  define FL_ICON_COLOR (Fl_Color)0xffffffff
+#  define FL_ICON_COLOR (Fl_Color)0xffffffff	/**< icon color [background?]*/
 
 
 //
@@ -90,57 +90,67 @@ class FL_EXPORT Fl_File_Icon			//// Icon data
   ~Fl_File_Icon();
 
   short		*add(short d);
-  /**  Adds a color value to the icon array, returning a pointer to it.*/
+
+  /**
+    Adds a color value to the icon array, returning a pointer to it.
+    \param[in] c color value
+  */
   short		*add_color(Fl_Color c)
 		{ short *d = add((short)COLOR); add((short)(c >> 16)); add((short)c); return (d); }
+
   /**
     Adds a vertex value to the icon array, returning a pointer to it.
-    The integer version accepts coordinates from 0 to 10000, while the
-    floating point version goes from 0.0 to 1.0. The origin (0.0) is in
-    the lower-lefthand corner of the icon.
+    The integer version accepts coordinates from 0 to 10000.
+    The origin (0.0) is in the lower-lefthand corner of the icon.
+    \param[in] x, y vertex coordinates
   */
   short		*add_vertex(int x, int y)
 		{ short *d = add((short)VERTEX); add((short)x); add((short)y); return (d); }
+
   /**
     Adds a vertex value to the icon array, returning a pointer to it.
-    The integer version accepts coordinates from 0 to 10000, while the
-    floating point version goes from 0.0 to 1.0. The origin (0.0) is in
-    the lower-lefthand corner of the icon.
+    The floating point version goes from 0.0 to 1.0.
+    The origin (0.0) is in the lower-lefthand corner of the icon.
+    \param[in] x, y vertex coordinates
   */
   short		*add_vertex(float x, float y)
 		{ short *d = add((short)VERTEX); add((short)(x * 10000.0));
 		  add((short)(y * 10000.0)); return (d); }
+
   /** Clears all icon data from the icon.*/
   void		clear() { num_data_ = 0; }
-  /** Draws the icon in the indicated area.*/
+
   void		draw(int x, int y, int w, int h, Fl_Color ic, int active = 1);
-  /** Set the widgets label to an icon */
+
   void		label(Fl_Widget *w);
-  /** The labeltype function for icons.*/
+
   static void	labeltype(const Fl_Label *o, int x, int y, int w, int h, Fl_Align a);
   void		load(const char *f);
   int		load_fti(const char *fti);
   int		load_image(const char *i);
+
   /** Returns next file icon object. See Fl_File_Icon::first() */
   Fl_File_Icon	*next() { return (next_); }
+
   /** Returns the filename matching pattern for the icon.*/
   const char	*pattern() { return (pattern_); }
+
   /**  Returns the number of words of data used by the icon.*/
   int		size() { return (num_data_); }
+
   /**
     Returns the filetype associated with the icon, which can be one of the
     following:
   
-    <UL>
-  	<LI>Fl_File_Icon::ANY, any kind of file.
-  	<LI>Fl_File_Icon::PLAIN, plain files.
-  	<LI>Fl_File_Icon::FIFO, named pipes.
-  	<LI>Fl_File_Icon::DEVICE, character and block devices.
-  	<LI>Fl_File_Icon::LINK, symbolic links.
-  	<LI>Fl_File_Icon::DIRECTORY, directories.
-    </UL>
+    \li Fl_File_Icon::ANY, any kind of file.
+    \li Fl_File_Icon::PLAIN, plain files.
+    \li Fl_File_Icon::FIFO, named pipes.
+    \li Fl_File_Icon::DEVICE, character and block devices.
+    \li Fl_File_Icon::LINK, symbolic links.
+    \li Fl_File_Icon::DIRECTORY, directories.
   */
   int		type() { return (type_); }
+
   /**  Returns the data array for the icon.*/
   short		*value() { return (data_); }
 

src/Fl_File_Icon.cxx

@@ -5,7 +5,7 @@
 //
 // KDE icon code donated by Maarten De Boer.
 //
-// Copyright 1999-2005 by Michael Sweet.
+// Copyright 1999-2008 by Michael Sweet.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -82,10 +82,13 @@ Fl_File_Icon	*Fl_File_Icon::first_ = (Fl_File_Icon *)0;
 
 
 /**
-  The constructor creates a new Fl_File_Icon with the specified
-  information.
+  Creates a new Fl_File_Icon with the specified information.
+  \param[in] p filename pattern
+  \param[in] t file type
+  \param[in] nd number of data values
+  \param[in] d data values
 */
-Fl_File_Icon::Fl_File_Icon(const char *p,	/**< I - Filename pattern */
+Fl_File_Icon::Fl_File_Icon(const char *p,	/* I - Filename pattern */
                 	   int        t,	/* I - File type */
 			   int        nd,	/* I - Number of data values */
 			   short      *d)	/* I - Data values */
@@ -143,7 +146,10 @@ Fl_File_Icon::~Fl_File_Icon() {
 }
 
 
-/** Adds a keyword value to the icon array, returning a pointer to it.*/
+/**
+  Adds a keyword value to the icon array, returning a pointer to it.
+  \param[in] d data value
+*/
 short *				// O - Pointer to new data value
 Fl_File_Icon::add(short d)	// I - Data to add
 {
@@ -174,7 +180,12 @@ Fl_File_Icon::add(short d)	// I - Data to add
 }
 
 
-/** Finds an icon that matches the given filename and file type.*/
+/**
+  Finds an icon that matches the given filename and file type.
+  \param[in] filename name of file
+  \param[in] filetype enumerated file type
+  \return matching file icon or NULL
+*/
 Fl_File_Icon *				// O - Matching file icon or NULL
 Fl_File_Icon::find(const char *filename,// I - Name of file */
                    int        filetype)	// I - Enumerated file type
@@ -236,7 +247,12 @@ Fl_File_Icon::find(const char *filename,// I - Name of file */
   return (current);
 }
 
-/** Drawsan icon. */
+/**
+  Draws an icon in the indicated area.
+  \param[in] x, y, w, h position and size
+  \param[in] ic icon color
+  \param[in] active status, default is active [non-zero]
+*/
 void
 Fl_File_Icon::draw(int      x,		// I - Upper-lefthand X
         	   int      y,		// I - Upper-lefthand Y
@@ -438,6 +454,7 @@ Fl_File_Icon::draw(int      x,		// I - Upper-lefthand X
 /**
   Applies the icon to the widget, registering the Fl_File_Icon
   label type as needed.
+  \param[in] w widget for which this icon will become the label
 */
 void Fl_File_Icon::label(Fl_Widget *w)	// I - Widget to label
 {
@@ -446,10 +463,12 @@ void Fl_File_Icon::label(Fl_Widget *w)	// I - Widget to label
 }
 
 
-//
-// 'Fl_File_Icon::labeltype()' - Draw the icon label.
-//
-
+/**
+  Draw the icon label.
+  \param[in] o label data
+  \param[in] x, y, w, h position and size of label
+  \param[in] a label alignment [not used]
+*/
 void
 Fl_File_Icon::labeltype(const Fl_Label *o,	// I - Label data
                 	int            x,	// I - X position of label

src/Fl_File_Icon2.cxx

@@ -5,7 +5,7 @@
 //
 // KDE icon code donated by Maarten De Boer.
 //
-// Copyright 1999-2005 by Michael Sweet.
+// Copyright 1999-2008 by Michael Sweet.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -98,7 +98,10 @@ static char	*get_kde_val(char *str, const char *key);
 static const char *kdedir = NULL;
 
 
-/** Loads the specified icon image. The format is deduced from the filename.*/
+/**
+  Loads the specified icon image. The format is deduced from the filename.
+  \param[in] f filename
+*/
 void
 Fl_File_Icon::load(const char *f)	// I - File to read from
 {
@@ -121,7 +124,11 @@ Fl_File_Icon::load(const char *f)	// I - File to read from
 }
 
 
-/** Loads an SGI icon file.*/
+/**
+  Loads an SGI icon file.
+  \param[in] fti icon filename
+  \return 0 on success, non-zero on error
+*/
 int					// O - 0 on success, non-zero on error
 Fl_File_Icon::load_fti(const char *fti)	// I - File to read from
 {
@@ -335,7 +342,11 @@ Fl_File_Icon::load_fti(const char *fti)	// I - File to read from
 }
 
 
-/** Load an image icon file from an image filename. Returns  0 on success, non-0 on error. */
+/**
+  Load an image icon file from an image filename.
+  \param[in] ifile image filename
+  \return 0 on success, non-zero on error
+*/
 int Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
 {
   Fl_Shared_Image	*img;		// Image file
@@ -577,9 +588,9 @@ int Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
 }
 
 
-/**  Loads all system-defined icons. This call is useful when using the
-  FileChooser widget and should be used when the application
-  starts:
+/**
+  Loads all system-defined icons. This call is useful when using the
+  FileChooser widget and should be used when the application starts:
   
   \code
   Fl_File_Icon::load_system_icons();