Documentation fixes and clarifications.

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

4 files changed, 98 insertions, 78 deletions

diff --git a/FL/Fl_Menu_.H b/FL/Fl_Menu_.H
index c609e7a8d..239258669 100644
--- a/FL/Fl_Menu_.H
+++ b/FL/Fl_Menu_.H
@@ -3,7 +3,7 @@
 //
 // Menu base class header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -29,24 +29,24 @@
 
 /**
   Base class of all widgets that have a menu in FLTK.
-  Currently FLTK provides you with 
-  Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice.
-  
-  <P>The class contains a pointer to an array of structures of type  Fl_Menu_Item.  The
-  array may either be supplied directly by the user program, or it may
+
+  Currently FLTK provides you with Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice.
+
+  The class contains a pointer to an array of structures of type Fl_Menu_Item.
+  The array may either be supplied directly by the user program, or it may
   be "private": a dynamically allocated array managed by the Fl_Menu_.
 
   When the user clicks a menu item, value() is set to that item
   and then:
 
-      - If the Fl_Menu_Item has a callback set, that callback
-        is invoked with any userdata configured for it.
-        (The Fl_Menu_ widget's callback is NOT invoked.
+    - If the Fl_Menu_Item has a callback set, that callback
+      is invoked with any userdata configured for it.
+      (The Fl_Menu_ widget's callback is NOT invoked.)
 
-      - For any Fl_Menu_Items that \b don't have a callback set,
-        the Fl_Menu_ widget's callback is invoked with any userdata
-        configured for it. The callback can determine which item
-        was picked using value(), mvalue(), item_pathname(), etc.
+    - For any Fl_Menu_Items that \b don't have a callback set,
+      the Fl_Menu_ widget's callback is invoked with any userdata
+      configured for it. The callback can determine which item
+      was picked using value(), mvalue(), item_pathname(), etc.
 */
 class FL_EXPORT Fl_Menu_ : public Fl_Widget {
 
@@ -106,12 +106,12 @@ public:
     }
     \endcode
 
-  */  
+  */
   const Fl_Menu_Item *menu() const {return menu_;}
   void menu(const Fl_Menu_Item *m);
   void copy(const Fl_Menu_Item *m, void* user_data = 0);
   int insert(int index, const char*, int shortcut, Fl_Callback*, void* = 0, int = 0);
-  int  add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0);
+  int  add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0); // see src/Fl_Menu_add.cxx
   /** See int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback*, void *user_data=0, int flags=0) */
   int  add(const char* a, const char* b, Fl_Callback* c, void* d = 0, int e = 0) {
       return add(a,fl_old_shortcut(b),c,d,e);
@@ -127,7 +127,7 @@ public:
   int clear_submenu(int index);
   void replace(int,const char *);
   void remove(int);
- /** Changes the shortcut of item i to n.  */
+  /** Changes the shortcut of item \p i to \p s. */
   void shortcut(int i, int s) {menu_[i].shortcut(s);}
   /** Sets the flags of item i.  For a list of the flags, see Fl_Menu_Item.  */
   void mode(int i,int fl) {menu_[i].flags = fl;}
@@ -166,9 +166,9 @@ public:
 
   /**
     This box type is used to surround the currently-selected items in the
-    menus.  If this is FL_NO_BOX then it acts like 
-    FL_THIN_UP_BOX and selection_color() acts like 
-    FL_WHITE, for back compatibility.    
+    menus.  If this is FL_NO_BOX then it acts like
+    FL_THIN_UP_BOX and selection_color() acts like
+    FL_WHITE, for back compatibility.
   */
   Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;}
   /**    See Fl_Boxtype Fl_Menu_::down_box() const   */
diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H
index 98127e33c..dcb76652a 100644
--- a/FL/Fl_Menu_Bar.H
+++ b/FL/Fl_Menu_Bar.H
@@ -3,7 +3,7 @@
 //
 // Menu bar header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -29,35 +29,39 @@
   put this widget along the top edge of your window.  The height of the
   widget should be 30 for the menu titles to draw correctly with the
   default font.
-  <P>The items on the bar and the menus they bring up are defined by a
-  single Fl_Menu_Item
-  array.  Because a Fl_Menu_Item array defines a hierarchy, the
+
+  The items on the bar and the menus they bring up are defined by a
+  single Fl_Menu_Item array.
+  Because a Fl_Menu_Item array defines a hierarchy, the
   top level menu defines the items in the menubar, while the submenus
   define the pull-down menus. Sub-sub menus and lower pop up to the right
-  of the submenus. </P>
-  <P ALIGN=CENTER>\image html  menubar.png</P>
+  of the submenus.
+
+  \image html  menubar.png
   \image latex  menubar.png " menubar" width=12cm
-  <P>If there is an item in the top menu that is not a title of a
+
+  If there is an item in the top menu that is not a title of a
   submenu, then it acts like a "button" in the menubar.  Clicking on it
-  will pick it. </P>
+  will pick it.
 
   When the user clicks a menu item, value() is set to that item
   and then:
 
-      - The item's callback is done if one has been set; the
-        Fl_Menu_Bar is passed as the Fl_Widget* argument, 
-        along with any userdata configured for the callback.
+    - The item's callback is done if one has been set; the
+      Fl_Menu_Bar is passed as the Fl_Widget* argument,
+      along with any userdata configured for the callback.
 
-      - If the item does not have a callback, the Fl_Menu_Bar's callback
-        is done instead, along with any userdata configured for the callback.
-        The callback can determine which item was picked using
-        value(), mvalue(), item_pathname(), etc.
+    - If the item does not have a callback, the Fl_Menu_Bar's callback
+      is done instead, along with any userdata configured for the callback.
+      The callback can determine which item was picked using
+      value(), mvalue(), item_pathname(), etc.
 
-  <P>Submenus will also pop up in response to shortcuts indicated by
+  Submenus will also pop up in response to shortcuts indicated by
   putting a '&' character in the name field of the menu item. If you put a
   '&' character in a top-level "button" then the shortcut picks it.  The
-  '&' character in submenus is ignored until the menu is popped up. </P>
-  <P>Typing the shortcut() of any of the menu items will cause
+  '&' character in submenus is ignored until the menu is popped up.
+
+  Typing the shortcut() of any of the menu items will cause
   callbacks exactly the same as when you pick the item with the mouse.
 */
 class FL_EXPORT Fl_Menu_Bar : public Fl_Menu_ {
@@ -66,20 +70,24 @@ protected:
 public:
     int handle(int);
   /**
-      Creates a new Fl_Menu_Bar widget using the given position,
+    Creates a new Fl_Menu_Bar widget using the given position,
     size, and label string. The default boxtype is FL_UP_BOX.
-    <P>The constructor sets menu() to NULL.  See 
-    Fl_Menu_ for the methods to set or change the menu. </P>
-    <P>labelsize(), labelfont(), and labelcolor()
+
+    The constructor sets menu() to NULL.  See
+    Fl_Menu_ for the methods to set or change the menu.
+
+    labelsize(), labelfont(), and labelcolor()
     are used to control how the menubar items are drawn.  They are
     initialized from the Fl_Menu static variables, but you can
-    change them if desired. </P>
-    <P>label() is ignored unless you change align() to
+    change them if desired.
+
+    label() is ignored unless you change align() to
     put it outside the menubar.
-    <P>The destructor removes the Fl_Menu_Bar widget and all of its
+
+    The destructor removes the Fl_Menu_Bar widget and all of its
     menu items.
   */
-  Fl_Menu_Bar(int X, int Y, int W, int H,const char *l=0);
+  Fl_Menu_Bar(int X, int Y, int W, int H, const char *l=0);
 };
 
 #endif
diff --git a/src/Fl_Menu_.cxx b/src/Fl_Menu_.cxx
index 6ab3797a3..487641a36 100644
--- a/src/Fl_Menu_.cxx
+++ b/src/Fl_Menu_.cxx
@@ -3,7 +3,7 @@
 //
 // Common menu code for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -154,8 +154,8 @@ const Fl_Menu_Item * Fl_Menu_::find_item(const char *pathname) {
 }
 
 /**
- Find the index the menu array for given \p item.
- 
+ Find the index into the menu array for a given \p item.
+
  A way to convert a menu item pointer into an index.
 
  Does \b not handle items that are in submenu pointers (FL_SUBMENU_POINTER).
@@ -175,7 +175,7 @@ const Fl_Menu_Item * Fl_Menu_::find_item(const char *pathname) {
    if ( index == -1 ) { ..error.. }
  \endcode
 
- \param item The *item to be found
+ \param[in]  item  The item to be found
  \returns    The index of the item, or -1 if not found.
  \see        menu()
 */
@@ -212,7 +212,7 @@ int Fl_Menu_::find_index(Fl_Callback *cb) const {
 
  To get the menu item pointer for a pathname, use find_item()
 
- \param pathname The path and name of the menu item index to find
+ \param[in] pathname The path and name of the menu item to find
  \returns        The index of the matching item, or -1 if not found.
  \see            item_pathname()
 
@@ -254,7 +254,7 @@ int Fl_Menu_::find_index(const char *pathname) const {
  internationalisation and a menu item can not be found using its label. This
  search is also much faster.
  
- \param cb find the first item with this callback
+ \param[in] cb find the first item with this callback
  \returns The item found, or NULL if not found
  \see find_item(const char*)
  */
@@ -482,7 +482,7 @@ void Fl_Menu_::clear() {
  is done to make a private array.
 
  \warning Since this method can change the internal menu array, any menu
- item pointers or indecies the application may have cached can become
+ item pointers or indices the application may have cached can become
  stale, and should be recalculated/refreshed.
 
  \b Example:
diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx
index 44aa34418..2406a383f 100644
--- a/src/Fl_Menu_add.cxx
+++ b/src/Fl_Menu_add.cxx
@@ -3,7 +3,7 @@
 //
 // Menu utilities for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -94,10 +94,14 @@ static int compare(const char* a, const char* b) {
 }
 
 
+/** Adds a menu item.
 
-/** Adds an item.  The text is split at '/' characters to automatically
-   produce submenus (actually a totally unnecessary feature as you can
-   now add submenu titles directly by setting SUBMENU in the flags):
+  The text is split at '/' characters to automatically
+  produce submenus (actually a totally unnecessary feature as you can
+  now add submenu titles directly by setting FL_SUBMENU in the flags).
+
+  \returns the index into the menu() array, where the entry was added
+  \see Fl_Menu_Item::insert(int, const char*, int, Fl_Callback*, void*, int)
 */
 int Fl_Menu_Item::add(
   const char *mytext,
@@ -110,7 +114,6 @@ int Fl_Menu_Item::add(
 }
 
 
-
 /** 
  Inserts an item at position \p index.
     
@@ -122,12 +125,13 @@ int Fl_Menu_Item::add(
 
  In all other aspects, the behavior of insert() is the same as add().
  
- \param index insert new items here
- \param mytext new label string, details see above
- \param sc keyboard shortcut for new item
- \param cb callback function for new item
- \param data user data for new item
- \param myflags menu flags as described in FL_Menu_Item
+ \param[in] index	insert new items here
+ \param[in] mytext	new label string, details see above
+ \param[in] sc		keyboard shortcut for new item
+ \param[in] cb		callback function for new item
+ \param[in] data	user data for new item
+ \param[in] myflags	menu flags as described in FL_Menu_Item
+
  \returns the index into the menu() array, where the entry was added
 */
 int Fl_Menu_Item::insert(
@@ -209,30 +213,33 @@ int Fl_Menu_Item::insert(
 }
 
 
-
 /**
   Adds a new menu item.
-  
-  \param[in] label    The text label for the menu item.
-  \param[in] shortcut Optional keyboard shortcut that can be an int or string; (FL_CTRL+'a') or "^a". Default 0 if none.
-  \param[in] callback Optional callback invoked when user clicks the item. Default 0 if none.
-  \param[in] userdata Optional user data passed as an argument to the callback. Default 0 if none.
-  \param[in] flags    Optional flags that control the type of menu item; see below. Default is 0 for none.
-  \returns            The index into the menu() array, where the entry was added.
-  
+
+  \param[in] label	The text label for the menu item.
+  \param[in] shortcut	Optional keyboard shortcut that can be an int or string:
+			(FL_CTRL+'a') or "^a". Default 0 if none.
+  \param[in] callback	Optional callback invoked when user clicks the item.
+			Default 0 if none.
+  \param[in] userdata	Optional user data passed as an argument to the callback.
+			Default 0 if none.
+  \param[in] flags	Optional flags that control the type of menu item;
+			see below. Default is 0 for none.
+  \returns		The index into the menu() array, where the entry was added.
+
   \par Description
   If the menu array was directly set with menu(x), then copy() is done 
   to make a private array.
   \par 
   Since this method can change the internal menu array, any menu item
-  pointers or indecies the application may have cached can become stale,
+  pointers or indices the application may have cached can become stale,
   and should be recalculated/refreshed.
   \par
   A menu item's callback must not add() items to its parent menu during the callback.
 
   <B>Detailed Description of Parameters</B>
   \par label
-  The menu item's label. This option is required.
+  The menu item's label. This argument is required and must not be NULL.
   \par
   The characters "&", "/", "\", and "_" are treated as special characters in the label string. 
   The "&" character specifies that the following character is an accelerator and will be underlined.
@@ -273,7 +280,7 @@ int Fl_Menu_Item::insert(
   \endverbatim
   \par
   ..where \<ascii_value\> is a decimal value representing an
-  ascii character (eg. 97 is the ascii code for 'a'), and the optional
+  ASCII character (eg. 97 is the ascii code for 'a'), and the optional
   prefixes enhance the value that follows. Multiple prefixes must
   appear in the order below.
   \par
@@ -313,6 +320,12 @@ int Fl_Menu_Item::insert(
       FL_MENU_DIVIDER      // Creates divider line below this item. Also ends a group of radio buttons.
   \endcode
 
+  If FL_SUBMENU is set in an item's flags, then actually two items are added:
+  the first item is the menu item (submenu title), as expected, and the second
+  item is the submenu terminating item with the label and all other members
+  set to 0. If you add submenus with the 'path' technique, then the
+  corresponding submenu terminators (maybe more than one) are added as well.
+
   \todo Raw integer shortcut needs examples. 
         Dependent on responses to http://fltk.org/newsgroups.php?gfltk.development+v:10086 and results of STR#2344
  */
@@ -321,7 +334,6 @@ int Fl_Menu_::add(const char *label,int shortcut,Fl_Callback *callback,void *use
 }
 
 
-
 /**
   Inserts a new menu item at the specified \p index position.
 
@@ -351,8 +363,8 @@ int Fl_Menu_::add(const char *label,int shortcut,Fl_Callback *callback,void *use
   \returns            The index into the menu() array, where the entry was added.
 
   \see                add()
+*/
 
- */
 int Fl_Menu_::insert(
   int index,
   const char *label,
@@ -365,7 +377,7 @@ int Fl_Menu_::insert(
   if (this != fl_menu_array_owner) {
     if (fl_menu_array_owner) {
       Fl_Menu_* o = fl_menu_array_owner;
-      // the previous owner get's its own correctly-sized array:
+      // the previous owner gets its own correctly-sized array:
       int value_offset = (int) (o->value_-local_array);
       int n = local_array_size;
       Fl_Menu_Item* newMenu = o->menu_ = new Fl_Menu_Item[n];