Doxygen documentation: Fixed most important warnings for the Fl_Widget, Fl_Window, Fl_Valuator classes that should be now a 100% documented. For the rest I drastically reduced the undocumented APIs, but many others (less important) remains.

It looks and feels pretty good now :-)


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

22 files changed, 180 insertions, 146 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 3ca344b0f..7690306ea 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -595,6 +595,10 @@ enum Fl_Labeltype {	// labeltypes:
   FL_FREE_LABELTYPE		///< first free labeltype to use for creating own labeltypes
 };
 
+/** 
+  Sets the current  label type end return its corresponding Fl_Labeltype value. 
+  @{
+*/
 #define FL_SYMBOL_LABEL FL_NORMAL_LABEL
 extern Fl_Labeltype FL_EXPORT fl_define_FL_SHADOW_LABEL();
 #define FL_SHADOW_LABEL fl_define_FL_SHADOW_LABEL()
@@ -602,6 +606,7 @@ extern Fl_Labeltype FL_EXPORT fl_define_FL_ENGRAVED_LABEL();
 #define FL_ENGRAVED_LABEL fl_define_FL_ENGRAVED_LABEL()
 extern Fl_Labeltype FL_EXPORT fl_define_FL_EMBOSSED_LABEL();
 #define FL_EMBOSSED_LABEL fl_define_FL_EMBOSSED_LABEL()
+/** @} */
 
 /** \name Alignment Flags */
 /*@{*/
diff --git a/FL/Fl.H b/FL/Fl.H
index 58a155464..bbd1e92d9 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -93,19 +93,22 @@ public: // should be private!
   static void damage(int d) {damage_ = d;}
 
   static void (*idle)();
+
+#ifndef FL_DOXYGEN
   static Fl_Awake_Handler *awake_ring_;
   static void **awake_data_;
   static int awake_ring_size_;
   static int awake_ring_head_;
   static int awake_ring_tail_;
-
-  static int add_awake_handler_(Fl_Awake_Handler, void*);
-  static int get_awake_handler_(Fl_Awake_Handler&, void*&);
-
   static const char* scheme_;
   static Fl_Image* scheme_bg_;
 
   static int e_original_keysym; // late addition
+#endif
+
+
+  static int add_awake_handler_(Fl_Awake_Handler, void*);
+  static int get_awake_handler_(Fl_Awake_Handler&, void*&);
 
 public:
 
diff --git a/FL/Fl_Button.H b/FL/Fl_Button.H
index ded1dfe9e..05b1b7585 100644
--- a/FL/Fl_Button.H
+++ b/FL/Fl_Button.H
@@ -36,10 +36,12 @@
 #endif
 
 // values for type()
-#define FL_NORMAL_BUTTON	0
-#define FL_TOGGLE_BUTTON	1
-#define FL_RADIO_BUTTON		(FL_RESERVED_TYPE+2)
-#define FL_HIDDEN_BUTTON	3 // for Forms compatibility
+#define FL_NORMAL_BUTTON	0   ///< value() remains unchanged after button press.
+#define FL_TOGGLE_BUTTON	1   ///< value() is inverted after button press.
+#define FL_RADIO_BUTTON		(FL_RESERVED_TYPE+2) /**< is set to 1 after button press, and all other
+				    buttons in the current group with <tt>type() == FL_RADIO_BUTTON</tt>
+				    are set to zero.*/
+#define FL_HIDDEN_BUTTON	3   ///< for Forms compatibility
 
 extern FL_EXPORT int fl_old_shortcut(const char*);
 
@@ -76,7 +78,6 @@ extern FL_EXPORT int fl_old_shortcut(const char*);
          (when the user pushes and releases the button, and as the mouse is
 	 dragged around in and out of the button).
 */
-
 class FL_EXPORT Fl_Button : public Fl_Widget {
 
   int shortcut_;
diff --git a/FL/Fl_Fill_Dial.H b/FL/Fl_Fill_Dial.H
index da5aa3fd7..db56c885f 100644
--- a/FL/Fl_Fill_Dial.H
+++ b/FL/Fl_Fill_Dial.H
@@ -33,8 +33,10 @@
 
 #include "Fl_Dial.H"
 
+/** Draws a dial with a filled arc */
 class Fl_Fill_Dial : public Fl_Dial {
 public:
+    /** Creates a filled dial, also setting its type to FL_FILL_DIAL. */
     Fl_Fill_Dial(int x,int y,int w,int h, const char *l = 0)
 	: Fl_Dial(x,y,w,h,l) {type(FL_FILL_DIAL);}
 };
diff --git a/FL/Fl_Fill_Slider.H b/FL/Fl_Fill_Slider.H
index 43cf2bffe..4ecf786ae 100644
--- a/FL/Fl_Fill_Slider.H
+++ b/FL/Fl_Fill_Slider.H
@@ -32,9 +32,10 @@
 #define Fl_Fill_Slider_H
 
 #include "Fl_Slider.H"
-
+/** Widget that draws a filled horizontal  slider,  useful as a progress or value meter*/
 class Fl_Fill_Slider : public Fl_Slider {
 public:
+    /** Creates the slider from its position,size and optional title. */
     Fl_Fill_Slider(int x,int y,int w,int h,const char *l=0)
 	: Fl_Slider(x,y,w,h,l) {type(FL_VERT_FILL_SLIDER);}
 };
diff --git a/FL/Fl_FormsBitmap.H b/FL/Fl_FormsBitmap.H
index 33ea92a46..308a2eda9 100644
--- a/FL/Fl_FormsBitmap.H
+++ b/FL/Fl_FormsBitmap.H
@@ -33,6 +33,9 @@
 
 #include "Fl_Bitmap.H"
 
+/** 
+    Forms compatibility Bitmap Image Widget
+*/
 class FL_EXPORT Fl_FormsBitmap : public Fl_Widget {
     Fl_Bitmap *b;
 protected:
@@ -40,7 +43,9 @@ protected:
 public:
     Fl_FormsBitmap(Fl_Boxtype, int, int, int, int, const char * = 0);
     void set(int W, int H, const uchar *bits);
+    /** Sets a new bitmap. */
     void bitmap(Fl_Bitmap *B) {b = B;}
+    /** Gets a the current associated Fl_Bitmap objects. */
     Fl_Bitmap *bitmap() const {return b;}
 };
 
diff --git a/FL/Fl_Help_View.H b/FL/Fl_Help_View.H
index 0e798db32..a2f48fa8c 100644
--- a/FL/Fl_Help_View.H
+++ b/FL/Fl_Help_View.H
@@ -72,25 +72,22 @@ struct Fl_Help_Block
 //
 // Fl_Help_Link structure...
 //
-
+/** Definition of a link for the html viewer*/
 struct Fl_Help_Link
 {
-  char		filename[192],	// Reference filename
-		name[32];	// Link target (blank if none)
-  int		x,		// X offset of link text
-		y,		// Y offset of link text
-		w,		// Width of link text
-		h;		// Height of link text
+  char		filename[192],	///< Reference filename
+		name[32];	///< Link target (blank if none)
+  int		x,		///< X offset of link text
+		y,		///< Y offset of link text
+		w,		///< Width of link text
+		h;		///< Height of link text
 };
 
-//
-// Fl_Help_Target structure...
-//
-
+/** Fl_Help_Target structure */
 struct Fl_Help_Target
 {
-  char		name[32];	// Target name
-  int		y;		// Y offset of target
+  char		name[32];	///< Target name
+  int		y;		///< Y offset of target
 };
 
 /**
@@ -100,43 +97,43 @@ struct Fl_Help_Target
 */
 class FL_EXPORT Fl_Help_View : public Fl_Group	//// Help viewer widget
 {
-  enum { RIGHT = -1, CENTER, LEFT };	// Alignments
+  enum { RIGHT = -1, CENTER, LEFT };	///< Alignments
 
-  char		title_[1024];		// Title string
-  Fl_Color	defcolor_,		// Default text color
-		bgcolor_,		// Background color
-		textcolor_,		// Text color
-		linkcolor_;		// Link color
-  Fl_Font       textfont_;		// Default font for text
-  Fl_Fontsize  textsize_;		// Default font size
-  const char	*value_;		// HTML text value
+  char		title_[1024];		///< Title string
+  Fl_Color	defcolor_,		///< Default text color
+		bgcolor_,		///< Background color
+		textcolor_,		///< Text color
+		linkcolor_;		///< Link color
+  Fl_Font       textfont_;		///< Default font for text
+  Fl_Fontsize  textsize_;		///< Default font size
+  const char	*value_;		///< HTML text value
 
-  int		nblocks_,		// Number of blocks/paragraphs
-		ablocks_;		// Allocated blocks
-  Fl_Help_Block	*blocks_;		// Blocks
+  int		nblocks_,		///< Number of blocks/paragraphs
+		ablocks_;		///< Allocated blocks
+  Fl_Help_Block	*blocks_;		///< Blocks
 
-  int		nfonts_;		// Number of fonts in stack
-  Fl_Font       fonts_[100];		// Font stack
-  Fl_Fontsize  font_sizes_[100];       // Font Size stack
+  int		nfonts_;		///< Number of fonts in stack
+  Fl_Font       fonts_[100];		///< Font stack
+  Fl_Fontsize  font_sizes_[100];        ///< Font Size stack
 
-  Fl_Help_Func	*link_;			// Link transform function
+  Fl_Help_Func	*link_;			///< Link transform function
 
-  int		nlinks_,		// Number of links
-		alinks_;		// Allocated links
-  Fl_Help_Link	*links_;		// Links
+  int		nlinks_,		///< Number of links
+		alinks_;		///< Allocated links
+  Fl_Help_Link	*links_;		///< Links
 
-  int		ntargets_,		// Number of targets
-		atargets_;		// Allocated targets
-  Fl_Help_Target *targets_;		// Targets
+  int		ntargets_,		///< Number of targets
+		atargets_;		///< Allocated targets
+  Fl_Help_Target *targets_;		///< Targets
 
-  char		directory_[1024];	// Directory for current file
-  char		filename_[1024];	// Current filename
-  int		topline_,		// Top line in document
-		leftline_,		// Lefthand position
-		size_,			// Total document length
-		hsize_;			// Maximum document width
-  Fl_Scrollbar	scrollbar_,		// Vertical scrollbar for document
-		hscrollbar_;		// Horizontal scrollbar
+  char		directory_[1024];	///< Directory for current file
+  char		filename_[1024];	///< Current filename
+  int		topline_,		///< Top line in document
+		leftline_,		///< Lefthand position
+		size_,			///< Total document length
+		hsize_;			///< Maximum document width
+  Fl_Scrollbar	scrollbar_,		///< Vertical scrollbar for document
+		hscrollbar_;		///< Horizontal scrollbar
 
   static int    selection_first;
   static int    selection_last;
diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index 8b8fdcabd..b0aeb3b69 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -114,15 +114,15 @@ class Fl_Menu_;
   releases of FLTK.
 */
 struct FL_EXPORT Fl_Menu_Item {
-  const char *text;	// label()
-  int shortcut_;
-  Fl_Callback *callback_;
-  void *user_data_;
-  int flags;
-  uchar labeltype_;
-  Fl_Font labelfont_;
-  Fl_Fontsize labelsize_;
-  unsigned labelcolor_;
+  const char *text;	    ///< menu item text, returned by label()
+  int shortcut_;	    ///<  menu item shortcut
+  Fl_Callback *callback_;   ///<  menu item callback
+  void *user_data_;	    ///<  menu item user_data for 3rd party apps
+  int flags;		    ///<  menu item flags like FL_MENU_TOGGLE,FL_MENU_RADIO
+  uchar labeltype_;	    ///<  how the menu item text looks like
+  Fl_Font labelfont_;	    ///<  which font for this menu item text
+  Fl_Fontsize labelsize_;   ///<  size of menu item text
+  unsigned labelcolor_;	    ///<  menu item text color 
 
   // advance N items, skipping submenus:
   const Fl_Menu_Item *next(int=1) const;
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 7ff43e9f5..950d155ca 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -458,7 +458,7 @@ public:
     operator const char *() { return data_; }
     ~Name();
   };
-
+  /** An entry associates a preference name to its corresponding value */
   struct Entry
   {
     char *name, *value;
diff --git a/FL/Fl_Round_Clock.H b/FL/Fl_Round_Clock.H
index cffed6a9d..33ad726ba 100644
--- a/FL/Fl_Round_Clock.H
+++ b/FL/Fl_Round_Clock.H
@@ -33,8 +33,10 @@
 
 #include "Fl_Clock.H"
 
+/** A clock widget of type FL_ROUND_CLOCK. Has no box. */
 class Fl_Round_Clock : public Fl_Clock {
 public:
+    /** Creates the clock widget, setting his type and box. */
     Fl_Round_Clock(int x,int y,int w,int h, const char *l = 0)
 	: Fl_Clock(x,y,w,h,l) {type(FL_ROUND_CLOCK); box(FL_NO_BOX);}
 };
diff --git a/FL/Fl_Simple_Counter.H b/FL/Fl_Simple_Counter.H
index 1b0c1a80d..0e1e1a4ef 100644
--- a/FL/Fl_Simple_Counter.H
+++ b/FL/Fl_Simple_Counter.H
@@ -32,7 +32,7 @@
 #define Fl_Simple_Counter_H
 
 #include "Fl_Counter.H"
-
+/** This widget creates a counter with only 2 arrow buttons */
 class Fl_Simple_Counter : public Fl_Counter {
 public:
     Fl_Simple_Counter(int x,int y,int w,int h, const char *l = 0)
diff --git a/FL/Fl_Text_Buffer.H b/FL/Fl_Text_Buffer.H
index 8fb746690..1aafb5228 100644
--- a/FL/Fl_Text_Buffer.H
+++ b/FL/Fl_Text_Buffer.H
@@ -276,36 +276,36 @@ class FL_EXPORT Fl_Text_Buffer {
 
     void update_selections(int pos, int nDeleted, int nInserted);
 
-    Fl_Text_Selection mPrimary; /* highlighted areas */
-    Fl_Text_Selection mSecondary;
-    Fl_Text_Selection mHighlight;
-    int mLength;                /* length of the text in the buffer (the length
+    Fl_Text_Selection mPrimary;   /**< highlighted areas */
+    Fl_Text_Selection mSecondary; /**< highlighted areas */
+    Fl_Text_Selection mHighlight; /**< highlighted areas */
+    int mLength;                /**< length of the text in the buffer (the length
                                    of the buffer itself must be calculated:
                                    gapEnd - gapStart + length) */
-    char* mBuf;                 /* allocated memory where the text is stored */
-    int mGapStart;              /* points to the first character of the gap */
-    int mGapEnd;                /* points to the first char after the gap */
+    char* mBuf;                 /**< allocated memory where the text is stored */
+    int mGapStart;              /**< points to the first character of the gap */
+    int mGapEnd;                /**< points to the first char after the gap */
     // The hardware tab distance used by all displays for this buffer,
     // and used in computing offsets for rectangular selection operations.
-    int mTabDist;               /* equiv. number of characters in a tab */
-    int mUseTabs;               /* True if buffer routines are allowed to use
+    int mTabDist;               /**< equiv. number of characters in a tab */
+    int mUseTabs;               /**< True if buffer routines are allowed to use
                                    tabs for padding in rectangular operations */
-    int mNModifyProcs;          /* number of modify-redisplay procs attached */
-    Fl_Text_Modify_Cb*          /* procedures to call when buffer is */
-    mNodifyProcs;               /* modified to redisplay contents */
-    void** mCbArgs;             /* caller arguments for modifyProcs above */
-    int mNPredeleteProcs;	/* number of pre-delete procs attached */
-    Fl_Text_Predelete_Cb*	/* procedure to call before text is deleted */
-	 mPredeleteProcs;	/* from the buffer; at most one is supported. */
-    void **mPredeleteCbArgs;	/* caller argument for pre-delete proc above */
-    int mCursorPosHint;         /* hint for reasonable cursor position after
+    int mNModifyProcs;          /**< number of modify-redisplay procs attached */
+    Fl_Text_Modify_Cb*          /**< procedures to call when buffer is */
+    mNodifyProcs;               /**< modified to redisplay contents */
+    void** mCbArgs;             /**< caller arguments for modifyProcs above */
+    int mNPredeleteProcs;	/**< number of pre-delete procs attached */
+    Fl_Text_Predelete_Cb*	/**< procedure to call before text is deleted */
+	 mPredeleteProcs;	/**< from the buffer; at most one is supported. */
+    void **mPredeleteCbArgs;	/**< caller argument for pre-delete proc above */
+    int mCursorPosHint;         /**< hint for reasonable cursor position after
                                    a buffer modification operation */
-    char mNullSubsChar;         /* NEdit is based on C null-terminated strings,
+    char mNullSubsChar;         /**< NEdit is based on C null-terminated strings,
                                    so ascii-nul characters must be substituted
                                    with something else.  This is the else, but
                                    of course, things get quite messy when you
                                    use it */
-    char mCanUndo;		/* if this buffer is used for attributes, it must
+    char mCanUndo;		/**< if this buffer is used for attributes, it must
 				   not do any undo calls */
 };
 
diff --git a/FL/Fl_Text_Display.H b/FL/Fl_Text_Display.H
index 08286e79d..87230084d 100644
--- a/FL/Fl_Text_Display.H
+++ b/FL/Fl_Text_Display.H
@@ -48,6 +48,7 @@
 */
 class FL_EXPORT Fl_Text_Display: public Fl_Group {
   public:
+    /** text display cursor shapes enumeration */
     enum {
       NORMAL_CURSOR, CARET_CURSOR, DIM_CURSOR,
       BLOCK_CURSOR, HEAVY_CURSOR
@@ -57,9 +58,10 @@ class FL_EXPORT Fl_Text_Display: public Fl_Group {
       CURSOR_POS, CHARACTER_POS
     };
 
-    // drag types- they match Fl::event_clicks() so that single clicking to
-    // start a collection selects by character, double clicking selects by
-    // word and triple clicking selects by line.
+    /** drag types- they match Fl::event_clicks() so that single clicking to
+        start a collection selects by character, double clicking selects by
+        word and triple clicking selects by line.
+    */
     enum {
       DRAG_CHAR = 0, DRAG_WORD = 1, DRAG_LINE = 2
     };
@@ -67,13 +69,14 @@ class FL_EXPORT Fl_Text_Display: public Fl_Group {
 
     typedef void (*Unfinished_Style_Cb)(int, void *);
 
-    // style attributes - currently not implemented!
+    /** style attributes - currently not implemented! */
     enum {
       ATTR_NONE = 0,
       ATTR_UNDERLINE = 1,
       ATTR_HIDDEN = 2
     };
-
+    /** This structure associates the color,font,size of a string to draw
+        with an attribute mask matching attr */
     struct Style_Table_Entry {
       Fl_Color	color;
       Fl_Font	font;
diff --git a/FL/Fl_Text_Editor.H b/FL/Fl_Text_Editor.H
index 75f72a35b..1c7ba221c 100644
--- a/FL/Fl_Text_Editor.H
+++ b/FL/Fl_Text_Editor.H
@@ -48,13 +48,15 @@
 */
 class FL_EXPORT Fl_Text_Editor : public Fl_Text_Display {
   public:
+    /** Key function binding callback type */
     typedef int (*Key_Func)(int key, Fl_Text_Editor* editor);
 
+    /** Simple linked list associating a key/state to a function */
     struct Key_Binding {
-      int          key;
-      int          state;
-      Key_Func     function;
-      Key_Binding* next;
+      int          key;		///< the key pressed
+      int          state;	///< the state of key modifiers
+      Key_Func     function;	///< associated function
+      Key_Binding* next;	///< next key binding in the list
     };
 
     Fl_Text_Editor(int X, int Y, int W, int H, const char* l = 0);
@@ -121,10 +123,12 @@ class FL_EXPORT Fl_Text_Editor : public Fl_Text_Display {
     int handle_key();
     void maybe_do_callback();
 
+#ifndef FL_DOXYGEN
     int insert_mode_;
     Key_Binding* key_bindings;
     static Key_Binding* global_key_bindings;
     Key_Func default_key_function_;
+#endif
 };
 
 #endif
diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index eb2d8a814..89dce8503 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -36,8 +36,8 @@
 #endif
 
 // shared type() values for classes that work in both directions:
-#define FL_VERTICAL		0
-#define FL_HORIZONTAL		1
+#define FL_VERTICAL		0 ///< The valuator can work vertically
+#define FL_HORIZONTAL		1 ///< The valuator can work horizontally
 
 /**
   The Fl_Valuator class controls a single floating-point value
@@ -59,16 +59,19 @@ class FL_EXPORT Fl_Valuator : public Fl_Widget {
   double A; int B; // rounds to multiples of A/B, or no rounding if A is zero
 
 protected:
-
-  int horizontal() const {return type()&1;}
+  /** Tells if the valuator is an FL_HORIZONTAL one */
+  int horizontal() const {return type()& FL_HORIZONTAL;}
   Fl_Valuator(int X, int Y, int W, int H, const char* L);
 
+  /** Gets the previous floating point value before an event changed it */
   double previous_value() const {return previous_value_;}
+  /** Stores the current value in the previous value */
   void handle_push() {previous_value_ = value_;}
   double softclamp(double);
   void handle_drag(double newvalue);
   void handle_release(); // use drag() value
   virtual void value_damage(); // cause damage() due to value() changing
+  /** Sets the current floating point value. */
   void set_value(double v) {value_ = v;}
 
 public:
diff --git a/FL/Fl_Value_Input.H b/FL/Fl_Value_Input.H
index f64a76b58..f17adcd06 100644
--- a/FL/Fl_Value_Input.H
+++ b/FL/Fl_Value_Input.H
@@ -63,6 +63,8 @@
 */
 class FL_EXPORT Fl_Value_Input : public Fl_Valuator {
 public:
+  /* This is the encapsulated Fl_input attribute to which 
+  this class delegates the value font, color and shortcut */
   Fl_Input input;
 private:
   char soft_;
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index 6992cd905..a0eba9e3a 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -38,9 +38,13 @@ class Fl_Window;
 class Fl_Group;
 class Fl_Image;
 
+/** Default callback type definition for all fltk widgets (by far the most used) */
 typedef void (Fl_Callback )(Fl_Widget*, void*);
+/** Default callback type pointer definition for all fltk widgets */
 typedef Fl_Callback* Fl_Callback_p; // needed for BORLAND
+/** One parameter Callback type definition passing only the widget */
 typedef void (Fl_Callback0)(Fl_Widget*);
+/** Callback type definition passing the widget and a long data value */
 typedef void (Fl_Callback1)(Fl_Widget*, long);
 
 
@@ -133,16 +137,28 @@ protected:
   void w(int v) {w_ = v;}
   /** Internal use only. Use position(int,int), size(int, int) or resize(int,int,int,int) instead. */
   void h(int v) {h_ = v;}
-
+  /** Gets the widget flags mask */
   int flags() const {return flags_;}
+  /** Sets a flag in the flags mask */
   void set_flag(int c) {flags_ |= c;}
+  /** Clears a flag in the flags mask */
   void clear_flag(int c) {flags_ &= ~c;}
-  enum {INACTIVE=1, INVISIBLE=2, OUTPUT=4, SHORTCUT_LABEL=64,
-        CHANGED=128, VISIBLE_FOCUS=512, COPIED_LABEL = 1024};
-
+  /** flags possible values enumeration.
+      See activate(),output(), visible(), changed(), set_visible_focus()
+  */
+  enum {
+        INACTIVE=1,	    ///< the widget can't receive focus, and is disabled but potentially visible
+        INVISIBLE=2,	    ///< the widget is not drawn but can receive events
+        OUTPUT=4,           ///< for output only
+        SHORTCUT_LABEL=64,  ///< the label contains a shortcut we need to draw
+        CHANGED=128,	    ///< the widget value changed
+        VISIBLE_FOCUS=512,  ///< accepts keyboard focus navigation if the widget can have the focus
+        COPIED_LABEL = 1024 ///< the widget label is internally copied, its destruction is handled by the widget
+       };
   void draw_box() const;
   void draw_box(Fl_Boxtype, Fl_Color) const;
   void draw_box(Fl_Boxtype, int,int,int,int, Fl_Color) const;
+  /** draws a focus rectangle around the widget */
   void draw_focus() {draw_focus(box(),x(),y(),w(),h());}
   void draw_focus(Fl_Boxtype, int,int,int,int) const;
   void draw_label() const;
@@ -864,9 +880,11 @@ public:
   void color2(unsigned a) {color2_ = a;}
 };
 
-// reserved type numbers (necessary for my cheapo RTTI) start here.
-// grep the header files for "RESERVED_TYPE" to find the next available
-// number.
+/**
+    Reserved type numbers (necessary for my cheapo RTTI) start here.
+    grep the header files for "RESERVED_TYPE" to find the next available
+    number.
+*/
 #define FL_RESERVED_TYPE 100
 
 #endif
diff --git a/FL/Fl_Window.H b/FL/Fl_Window.H
index f6561741e..19284d551 100644
--- a/FL/Fl_Window.H
+++ b/FL/Fl_Window.H
@@ -33,8 +33,8 @@
 
 #include "Fl_Group.H"
 
-#define FL_WINDOW 0xF0	// all subclasses have type() >= this
-#define FL_DOUBLE_WINDOW 0xF1
+#define FL_WINDOW 0xF0		///< window type id all subclasses have type() >= this
+#define FL_DOUBLE_WINDOW 0xF1   ///< double window type id
 
 class Fl_X;
 
@@ -85,6 +85,7 @@ class FL_EXPORT Fl_Window : public Fl_Group {
 
 protected:
 
+ /**  Stores the last window that was made current. See current() const */
   static Fl_Window *current_;
   virtual void draw();
   /** Forces the window to be drawn, this window is also made current and calls draw(). */
@@ -165,9 +166,7 @@ public:
     off. It only works before show() is called.
   */
   void clear_border()	{set_flag(FL_NOBORDER);}
-  /**
-    See int Fl_Window::border(int) 
-  */
+  /** See int Fl_Window::border(int) */
   int border() const	{return !(flags() & FL_NOBORDER);}
   /** Activate the flags FL_NOBORDER|FL_OVERRIDE */
   void set_override()	{set_flag(FL_NOBORDER|FL_OVERRIDE);}
@@ -183,9 +182,7 @@ public:
     Fl::modal().
   */
   void set_modal()	{set_flag(FL_MODAL);}
-  /**
-    Returns true if this window is modal.
-  */
+  /**  Returns true if this window is modal.  */
   int modal() const	{return flags() & FL_MODAL;}
   /**
     A "non-modal" window (terminology borrowed from Microsoft Windows)
@@ -194,9 +191,7 @@ public:
     window: modal, non-modal, and normal.
   */
   void set_non_modal()	{set_flag(FL_NON_MODAL);}
-  /**
-    Returns true if this window is modal or non-modal.
-  */
+  /**  Returns true if this window is modal or non-modal. */
   int non_modal() const {return flags() & (FL_NON_MODAL|FL_MODAL);}
 
   /**
@@ -207,13 +202,9 @@ public:
     does not work with some X window managers). \see position()
   */
   void hotspot(int x, int y, int offscreen = 0);
-  /**
-    See void Fl_Window::hotspot(int x, int y, int offscreen = 0) 
-  */
+  /** See void Fl_Window::hotspot(int x, int y, int offscreen = 0) */
   void hotspot(const Fl_Widget*, int offscreen = 0);
-  /**
-    See void Fl_Window::hotspot(int x, int y, int offscreen = 0) 
-  */
+  /** See void Fl_Window::hotspot(int x, int y, int offscreen = 0) */
   void hotspot(const Fl_Widget& p, int offscreen = 0) {hotspot(&p,offscreen);}
   /**
     Undoes the effect of a previous resize() or show()
@@ -258,27 +249,18 @@ public:
   void size_range(int a, int b, int c=0, int d=0, int e=0, int f=0, int g=0) {
     minw=a; minh=b; maxw=c; maxh=d; dw=e; dh=f; aspect=g; size_range_();}
 
-  /**
-    See void Fl_Window::label(const char*) 
-  */
+  /** See void Fl_Window::label(const char*)   */
   const char* label() const	{return Fl_Widget::label();}
-  /**
-    See void Fl_Window::iconlabel(const char*) 
-  */
+  /**  See void Fl_Window::iconlabel(const char*)   */
   const char* iconlabel() const	{return iconlabel_;}
-  /**
-    Gets or sets the window title bar label.
-  */
+  /** Sets the window title bar label.  */
   void label(const char*);
-  /**
-    Gets or sets the icon label.
-  */
+  /** Sets the icon label. */
   void iconlabel(const char*);
-  void label(const char* label, const char* iconlabel);
+  /** Gets or sets the icon label. */
+  void label(const char* label, const char* iconlabel); // platform dependent 
   void copy_label(const char* a);
-  /**
-    See void Fl_Window::xclass(const char*) 
-  */
+  /** See void Fl_Window::xclass(const char*) */
   const char* xclass() const	{return xclass_;}
   /**
     A string used to tell the system what type of window this is. Mostly
@@ -353,7 +335,7 @@ public:
   int x_root() const ;
   int y_root() const ;
 
-  static Fl_Window *current();
+ static Fl_Window *current();
   /**
     Sets things up so that the drawing functions in &lt;FL/fl_draw.H&gt; will go into this
     window. This is useful for incremental update of windows, such as in an
@@ -370,14 +352,15 @@ public:
     Changes the cursor for this window.  This always calls the system, if
     you are changing the cursor a lot you may want to keep track of how
     you set it in a static varaible and call this only if the new cursor
-    is different.
-    
+    is different. 
+
     <P>The type Fl_Cursor is an enumeration defined in  &lt;Enumerations.H&gt;.
     (Under X you can get any XC_cursor value by passing 
     Fl_Cursor((XC_foo/2)+1)).  The colors only work on X, they are
     not implemented on WIN32.
+    <P> For back compatibility only. 
   */
-  void cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE);
+  void cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE); // platform dependent
   void default_cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE);
   static void default_callback(Fl_Window*, void* v);
 
diff --git a/FL/glut.H b/FL/glut.H
index 1cc242c26..dcd5b311d 100644
--- a/FL/glut.H
+++ b/FL/glut.H
@@ -408,7 +408,10 @@ FL_EXPORT GLUTproc glutGetProcAddress(const char *procName);
 //inline void glutVideoPan(int x, int y, int width, int height);
 
 // Font argument must be a void* for compatability, so...
-extern FL_EXPORT struct Fl_Glut_Bitmap_Font {Fl_Font font; Fl_Fontsize size;}
+/** fltk glut font/size attributes used in the glutXXX functions */
+Fl_Glut_Bitmap_Font {Fl_Font font; Fl_Fontsize size;}
+
+extern FL_EXPORT struct Fl_Glut_Bitmap_Font
   glutBitmap9By15, glutBitmap8By13, glutBitmapTimesRoman10,
   glutBitmapTimesRoman24, glutBitmapHelvetica10, glutBitmapHelvetica12,
   glutBitmapHelvetica18;
diff --git a/FL/mac.H b/FL/mac.H
index fad685102..384501a60 100644
--- a/FL/mac.H
+++ b/FL/mac.H
@@ -28,8 +28,9 @@
 // Do not directly include this file, instead use <FL/x.H>.  It will
 // include this file if "__APPLE__" is defined.  This is to encourage
 // portability of even the system-specific code...
+#ifndef FL_DOXYGEN
 
-#ifndef Fl_X_H
+#if !defined(Fl_X_H)
 #  error "Never use <FL/mac.H> directly; include <FL/x.H> instead."
 #endif // !Fl_X_H
 
@@ -129,7 +130,7 @@ extern void fl_open_display();
 extern void fl_open_callback(void (*cb)(const char *));
 
 extern FL_EXPORT int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b);
-
+#endif // FL_DOXYGEN
 //
 // End of "$Id$".
 //
diff --git a/FL/win32.H b/FL/win32.H
index ad1b69369..e58dbfb39 100644
--- a/FL/win32.H
+++ b/FL/win32.H
@@ -29,6 +29,7 @@
 // include this file if WIN32 is defined.  This is to encourage
 // portability of even the system-specific code...
 
+#ifndef FL_DOXYGEN
 #ifndef Fl_X_H
 #  error "Never use <FL/win32.H> directly; include <FL/x.H> instead."
 #endif // !Fl_X_H
@@ -146,7 +147,7 @@ extern FL_EXPORT void fl_delete_bitmask(Fl_Bitmask bm);
 inline void fl_open_callback(void (*)(const char *)) {}
 
 extern FL_EXPORT int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b);
-
+#endif // FL_DOXYGEN
 //
 // End of "$Id$".
 //
diff --git a/FL/x.H b/FL/x.H
index 1c23ee520..2049d5bd3 100644
--- a/FL/x.H
+++ b/FL/x.H
@@ -30,7 +30,7 @@
 // need to call Xlib directly.  These symbols may not exist on non-X
 // systems.
 
-#ifndef Fl_X_H
+#if !defined(Fl_X_H) && !defined(FL_DOXYGEN) 
 #  define Fl_X_H
 
 #  include "Enumerations.H"