Some small Fl_Sys_Menu_Bar related doc mods as per STR#3317.

WIP -- more to come; just checking in what I have for now..

	1) rank -> index
	2) Added docs for index \return values for some methods 
	3) Some clarification in the internal docs about rank vs. index
	4) Enabled Fl_Menu_Item's enum flags to be able to be links (added @file
	   to Fl_Menu_Item.H) so references to e.g. "::FL_MENU_TOGGLE" will show
	   up as links in doxygen docs.



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

FL/Fl_Menu_.H

@@ -111,7 +111,7 @@ public:
   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);

FL/Fl_Menu_Item.H

@@ -26,6 +26,9 @@
 #    undef check
 #  endif
 
+// doxygen needs the following line to enable e.g. ::FL_MENU_TOGGLE to link to the enums
+/// @file
+
 enum { // values for flags:
   FL_MENU_INACTIVE = 1,		///< Deactivate menu item (gray out)
   FL_MENU_TOGGLE= 2,		///< Item is a checkbox toggle (shows checkbox for on/off state)

FL/Fl_Sys_Menu_Bar.H

@@ -65,7 +65,7 @@ public:
     return insert(index, label, fl_old_shortcut(shortcut), cb, user_data, flags);
     }
   void remove(int n);
-  void replace(int rank, const char *name);
+  void replace(int index, const char *name);
   /** Set the Fl_Menu_Item array pointer to null, indicating a zero-length menu. 
    \see Fl_Menu_::clear()
    */

src/Fl_Menu_add.cxx

@@ -97,7 +97,10 @@ static int compare(const char* a, const char* b) {
 
 /** 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):
+   now add submenu titles directly by setting 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 myflags)
 */
 int Fl_Menu_Item::add(
   const char *mytext,

src/Fl_Sys_Menu_Bar.mm

@@ -56,8 +56,12 @@ extern void (*fl_unlock_function)();
 
 /*  Each MacOS system menu item contains a pointer to a record of type sys_menu_item defined below.
     The purpose of these records is to associate each MacOS system menu item with a relevant Fl_Menu_Item.
+
+    Note: in the below, 'rank' is similar to an FLTK menu() 'index'.
+    Let's avoid exposing Mac internal terminology like 'rank' to FLTK users; stick with 'index'.
+
     If use_rank is YES, the "rank" field is used, and fl_sys_menu_bar->menu() + rank is the address 
-	of the relevant Fl_Menu_Item;
+    of the relevant Fl_Menu_Item;
     Otherwise, the "item" field points to the relevant Fl_Menu_Item.
     This allows the MacOS system menu to use the same Fl_Menu_Item's as those used by FLTK menus, 
     the address of which can be relocated by the FLTK menu logic.
@@ -176,7 +180,7 @@ typedef struct {
 						action:selector
 					 keyEquivalent:@""];
   sys_menu_item smi;
-  // ≥ 0 if mitem is in the menu items of fl_sys_menu_bar, -1 if not
+  // >= 0 if mitem is in the menu items of fl_sys_menu_bar, -1 if not
   smi.rank = (fl_sys_menu_bar ? fl_sys_menu_bar->find_index(mitem) : -1);
   smi.use_rank = (smi.rank >= 0);
   if (!smi.use_rank) smi.item = mitem;
@@ -354,10 +358,15 @@ void Fl_Sys_Menu_Bar::menu(const Fl_Menu_Item *m)
 
 
 /**
- * @brief add to the system menu bar a new menu item
+ * @brief Add a new menu item to the system menu bar.
  *
- * add to the system menu bar a new menu item, with a title string, shortcut int,
- * callback, argument to the callback, and flags.
+ * @param label     - new menu item's label
+ * @param shortcut  - new menu item's integer shortcut (can be 0 for none, or e.g. FL_ALT+'x')
+ * @param cb        - callback to be invoked when item selected (can be 0 for none, in which case the menubar's callback() can be used instead)
+ * @param user_data - argument to the callback
+ * @param flags     - item's flags, e.g. ::FL_MENU_TOGGLE, etc.
+ *
+ * \returns the index into the menu() array, where the entry was added
  *
  * @see Fl_Menu_::add(const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags) 
  */
@@ -371,7 +380,8 @@ int Fl_Sys_Menu_Bar::add(const char* label, int shortcut, Fl_Callback *cb, void
 
 /**
  * Forms-compatible procedure to add items to the system menu bar
-*
+ *
+ * \returns the index into the menu() array, where the entry was added
  * @see Fl_Menu_::add(const char* str) 
  */
 int Fl_Sys_Menu_Bar::add(const char* str)
@@ -385,9 +395,10 @@ int Fl_Sys_Menu_Bar::add(const char* str)
 /**
  * @brief insert in the system menu bar a new menu item
  *
- * insert in the system menu bar a new menu item, with a title string, shortcut int,
+ * Insert in the system menu bar a new menu item, with a title string, shortcut int,
  * callback, argument to the callback, and flags.
  *
+ * \returns the index into the menu() array, where the entry was inserted
  * @see Fl_Menu_::insert(int index, const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags) 
  */
 int Fl_Sys_Menu_Bar::insert(int index, const char* label, int shortcut, Fl_Callback *cb, void *user_data, int flags)
@@ -414,11 +425,11 @@ int Fl_Sys_Menu_Bar::clear_submenu(int index)
 /**
  * @brief remove an item from the system menu bar
  *
- * @param rank		the rank of the item to remove
+ * @param index		the index of the item to remove
  */
-void Fl_Sys_Menu_Bar::remove(int rank)
+void Fl_Sys_Menu_Bar::remove(int index)
 {
-  Fl_Menu_::remove(rank);
+  Fl_Menu_::remove(index);
   update();
 }
 
@@ -426,12 +437,12 @@ void Fl_Sys_Menu_Bar::remove(int rank)
 /**
  * @brief rename an item from the system menu bar
  *
- * @param rank		the rank of the item to rename
+ * @param index		the index of the item to rename
  * @param name		the new item name as a UTF8 string
  */
-void Fl_Sys_Menu_Bar::replace(int rank, const char *name)
+void Fl_Sys_Menu_Bar::replace(int index, const char *name)
 {
-  Fl_Menu_::replace(rank, name);
+  Fl_Menu_::replace(index, name);	// index
   update();
 }