reworked doxygen comments for Fl::arg() and Fl::args() - part 1

harmonised parameter names in Fl.H and Fl_arg.cxx and reworked
doxygen comments to make them a bit clearer. More work required.



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

2 files changed, 64 insertions, 50 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index d96507ccc..e94c9d1cc 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -176,9 +176,9 @@ public:
   static double version();
 
   // argument parsers:
-  static int arg(int, char**, int&);
-  static int args(int, char**, int&, Fl_Args_Handler ah = 0);
-  static void args(int, char**);
+  static int arg(int argc, char **argv, int& i);
+  static int args(int argc, char **argv, int& i, Fl_Args_Handler cb = 0);
+  static void args(int argc, char **argv);
   /**
     Usage string displayed if Fl::args() detects an invalid argument.
     This may be changed to point to customized text at run-time.
diff --git a/src/Fl_arg.cxx b/src/Fl_arg.cxx
index d6d46a4dc..c46f2af6f 100644
--- a/src/Fl_arg.cxx
+++ b/src/Fl_arg.cxx
@@ -68,11 +68,14 @@ extern const char *fl_bg;
 extern const char *fl_bg2;
 
 /**
-  Consume a single switch from argv, starting at word i.
+  Parse a single switch from \p argv, starting at word \p i.
   Returns the number of words eaten (1 or 2, or 0 if it is not
-  recognized) and adds the same value to i.  You can use this
-  function if you prefer to control the incrementing through the
-  arguments yourself.
+  recognized) and adds the same value to \p i. 
+  
+  You can use this function if you prefer to control the incrementing
+  through the standard FLTK switches yourself. If you want to handle
+  additional switches, you will need to provide your own argument handler
+  and pass it to Fl::args(int,char**,int&,Fl_Args_Handler) explicitly.
 */
 int Fl::arg(int argc, char **argv, int &i) {
   arg_called = 1;
@@ -167,48 +170,51 @@ int Fl::arg(int argc, char **argv, int &i) {
 }
 
 
-/** 
-  Consume all switches from argv.  Returns number of words eaten
-  Returns zero on error.  'i' will either point at first word that
-  does not start with '-', at the error word, or after a '--', or at
-  argc.  If your program does not take any word arguments you can
-  report an error if i < argc.
-  
-  <P>FLTK provides an <I>entirely optional</I> command-line switch parser.
-  You don't have to call it if you don't like them! Everything it can do
-  can be done with other calls to FLTK.
-  
-  <P>To use the switch parser, call Fl::args(...) near the start
-  of your program.  This does <I>not</I> open the display, instead
-  switches that need the display open are stashed into static variables.
-  Then you <I>must</I> display your first window by calling 
-  window-&gt;show(argc,argv), which will do anything stored in the
-  static variables.
-  
-  <P>callback lets you define your own switches.  It is called
-  with the same argc and argv, and with i the
-  index of each word. The callback should return zero if the switch is
-  unrecognized, and not change i.  It should return non-zero if
-  the switch is recognized, and add at least 1 to i (it can add
-  more to consume words after the switch).  This function is called
-  <i>before</i> any other tests, so <i>you can override any FLTK
-  switch</i> (this is why FLTK can use very short switches instead of
+/**
+  Parse command line switches using the \p cb argument handler.
+  
+  Returns 0 on error, or the number of words eaten.
+  
+  After the call returns, \p i will either point at the first word
+  that does not start with '-', or the word that does not match a
+  valid switch, or after a '--' denoting the end of the switches,
+  or at \p argc. If your program does not take any additional
+  arguments you can report an error if <tt>i < argc</tt>.
+  
+  FLTK provides this as an <i>entirely optional</i> command line
+  switch parser. You don't have to call it if you don't want to.
+  Everything it can do can be done with other calls to FLTK
+  
+  To use the switch parser, call Fl::args(...) near the start
+  of your program.  This does \b not open the display, instead
+  switches that need the display open are stashed into static
+  variables. Then you \b must display your first window by calling
+  <tt>window->show(argc,argv)</tt>, which will do anything stored
+  in the static variables.
+  
+  The \p cb argument handler lets you define your own switches.
+  It is called with the same \p argc and \p argv, and with \p i
+  the index of each word. The \p cb handler should return zero
+  if the switch is unrecognized, and not change \p i. It should
+  return non-zero if the switch is recognized, and add at least
+  1 to \p i (it can add more to consume words after the switch). 
+  This \p cb handler is called \i before any other tests, so
+  <i>you can also override any standard FLTK switch</i>
+  (this is why FLTK can use very short switches instead of
   the long ones all other toolkits force you to use).
-  
-  <P>On return i is set to the index of the first non-switch.
+ 
+  On return \p i is set to the index of the first non-switch.
   This is either:
   
-  <UL>
-  <LI>The first word that does not start with '-'. </LI>
-  <LI>The word '-' (used by many programs to name stdin as a file) </LI>
-  <LI>The first unrecognized switch (return value is 0). </LI>
-  <LI>argc</LI>
-  </UL>
+  - The first word that does not start with '-'.
+  - The word '-' (used by many programs to name stdin as a file)
+  - The first unrecognized switch (return value is 0).
+  - \p argc
   
-  <P>The return value is i unless an unrecognized switch is found,
+  The return value is \p i unless an unrecognized switch is found,
   in which case it is zero.  If your program takes no arguments other
   than switches you should produce an error if the return value is less
-  than argc.
+  than \p argc.
   
   <P>All switches except -bg2 may be abbreviated one letter and case is ignored:
   
@@ -268,13 +274,13 @@ int Fl::arg(int argc, char **argv, int &i) {
   
   </UL>
   
-  <P>The second form of Fl::args() is useful if your program does
-  not have command line switches of its own. It parses all the switches,
-  and if any are not recognized it calls Fl::abort(Fl::help).
-  
-  <P>A usage string is displayed if Fl::args() detects an invalid
-  argument on the command-line. You can change the message by setting the
+  A usage string is displayed if Fl::args() detects an invalid argument
+  on the command-line. You can change the message by setting the
   Fl::help pointer.
+  
+  The simpler Fl::args(int argc, char **argv) form is useful if your program
+  does not have command line switches of its own. It parses all the switches,
+  and if any are not recognized it calls Fl::abort(Fl::help).
 */
 
 int Fl::args(int argc, char** argv, int& i, Fl_Args_Handler cb) {
@@ -387,7 +393,15 @@ static const char * const helpmsg =
 " -to[oltips]";
 
 const char * const Fl::help = helpmsg+13;
-/** See Fl::args(int argc, char **argv, int& i, int (*cb)(int,char**,int&)) */
+
+/**
+ * Parse all command line switches matching standard FLTK options only.
+ * 
+ * This calls Fl::args(int,char**,int&,Fl_Args_Handler) with the
+ * argument handler set to the Fl::arg(int,char**,int&) function.
+ * 
+ * Note: an unexpected switch will cause an error message and program exit.
+ */
 void Fl::args(int argc, char **argv) {
   int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg);
 }