Simplified the doxygen comment strategy for fl_color_command()

Too many \defgroup, \ingroup and \relatesalso and doxygen gets confused!
Simplified down to a single \relatesalso, and moved the extra function
documentation into the class comments.



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

3 files changed, 48 insertions, 38 deletions

diff --git a/FL/Fl_Color_Chooser.H b/FL/Fl_Color_Chooser.H
index d55850331..34a12c436 100644
--- a/FL/Fl_Color_Chooser.H
+++ b/FL/Fl_Color_Chooser.H
@@ -73,14 +73,33 @@ public:
   \class Fl_Color_Chooser
   \brief The Fl_Color_Chooser widget provides a standard RGB color chooser.
 
-  You can place any number of these into a panel of your own design. This
-  widget contains the hue box, value slider, and rgb input fields from the
-  above diagram (it does not have the color chips or the Cancel or OK buttons).
+  \image html fl_color_chooser.jpg
+
+  You can place any number of the widgets into a panel of your own design.
+  The diagram shows the widget as part of a color chooser dialog created by
+  the fl_color_chooser() function. The Fl_Color_Chooser widget contains the
+  hue box, value slider, and rgb input fields from the above diagram (it
+  does not have the color chips or the Cancel or OK buttons).
   The callback is done every time the user changes the rgb value. It is not
   done if they move the hue control in a way that produces the \e same rgb
   value, such as when saturation or value is zero.
 
-  \image html fl_color_chooser.jpg
+  The fl_color_chooser() function pops up a window to let the user pick an
+  arbitrary RGB color. They can pick the hue and saturation in the "hue box"
+  on the left (hold down CTRL to just change the saturation), and the
+  brightness using the vertical slider. Or they can type the 8-bit numbers
+  into the RGB Fl_Value_Input fields, or drag the mouse across them to adjust
+  them.  The pull-down menu lets the user set the input fields to show RGB,
+  HSV, or 8-bit RGB (0 to 255).
+
+  fl_color_chooser() returns non-zero if the user picks ok, and updates the
+  RGB values.  If the user picks cancel or closes the window this returns
+  zero and leaves RGB unchanged.
+
+  If you use the color chooser on an 8-bit screen, it will allocate all the
+  available colors, leaving you no space to exactly represent the color the
+  user picks! You can however use fl_rectf() to fill a region with a simulated
+  color using dithering.
  */
 class FL_EXPORT Fl_Color_Chooser : public Fl_Group {
   Flcc_HueBox huebox;
diff --git a/documentation/development.dox b/documentation/development.dox
index 280c87fdf..c869a1040 100644
--- a/documentation/development.dox
+++ b/documentation/development.dox
@@ -91,6 +91,28 @@ From Duncan: (will be removed later, just for now as a reminder)
    we can add it to a functions.dox file that defines a functions group
    and do that for all of the function documentation?)
 
+\b Update: the trick is not to create duplicate entries in a new group, but
+   to move the function information into the doxygen comments for the
+   class, and use the navigation links provided. Simply using \\relatesalso
+   as the first doxygen command in the function's comment puts it in the
+   appropriate place. There is no need to have \\defgroup and \\ingroup as
+   well, and indeed they don't work. So, to summarize:
+\code
+Gizmo.H
+  /## \class Gizmo
+      A gizmo that does everything
+    #/
+  class Gizmo {
+    etc
+  };
+  extern int popup_gizmo(...);
+
+Gizmo.cxx:
+  /## \relatesalso Gizmo
+      Pops up a gizmo dialog with a Gizmo in it
+    #/
+  int popup_gizmo(...);
+\endcode
 
 <H3>Example comment:</H3>
 
diff --git a/src/Fl_Color_Chooser.cxx b/src/Fl_Color_Chooser.cxx
index dad84c312..d06393e16 100644
--- a/src/Fl_Color_Chooser.cxx
+++ b/src/Fl_Color_Chooser.cxx
@@ -507,39 +507,9 @@ extern const char* fl_ok;
 extern const char* fl_cancel;
 
 /**
-  \defgroup fl_color_chooser_group fl_color_chooser()
-
-  \code #include <FL/Fl_Color_Chooser.H> \endcode
-
-  The double version takes RGB values in the range 0.0 to 1.0.
-  The uchar version takes RGB values in the range 0 to 255.
-  The \p name argument specifies the label (title) for the window.
-
-  \image html fl_color_chooser.jpg
-
-  fl_color_chooser() pops up a window to let the user pick an arbitrary RGB
-  color. They can pick the hue and saturation in the "hue box" on the left
-  (hold down CTRL to just change the saturation), and the brighness using
-  the vertical slider. Or they can type the 8-bit numbers into the RGB
-  Fl_Value_Input fields, or drag the mouse across them to adjust them.
-  The pull-down menu lets the user set the input fields to show RGB, HSV,
-  or 8-bit RGB (0 to 255).
-
-  This returns non-zero if the user picks ok, and updates the RGB values.
-  If the user picks cancel or closes the window this returns zero and leaves
-  RGB unchanged.
-
-  If you use the color chooser on an 8-bit screen, it will allocate all the
-  available colors, leaving you no space to exactly represent the color the
-  user picks! You can however use fl_rectf() to fill a region with a simulated
-  color using dithering.
- */
-
-/** \relatesalso Fl_Color_Chooser
-  \ingroup fl_color_chooser_group
+  \relatesalso Fl_Color_Chooser
   \fn int fl_color_chooser(const char* name, double& r, double& g, double& b)
   \brief Pops up a window to let the user pick an arbitrary RGB color.
-  
   \param[in] name title label for the window
   \param[in] r, g, b color components in the range 0.0 to 1.0.
  */
@@ -577,11 +547,10 @@ int fl_color_chooser(const char* name, double& r, double& g, double& b) {
   return 0;
 }
 
-/** \relatesalso Fl_Color_Chooser
-  \ingroup fl_color_chooser_group
+/**
+  \relatesalso Fl_Color_Chooser
   \fn int fl_color_chooser(const char* name, uchar& r, uchar& g, uchar& b)
   \brief Pops up a window to let the user pick an arbitrary RGB color.
-  
   \param[in] name title label for the window
   \param[in] r, g, b color components in the range 0 to 255.
  */