Improve documentation of Fl_Box constructors (#1194)

Separate both constructor types and document parameters.

1 files changed, 37 insertions, 12 deletions

diff --git a/FL/Fl_Box.H b/FL/Fl_Box.H
index 56e1ff5ce..37bef87ca 100644
--- a/FL/Fl_Box.H
+++ b/FL/Fl_Box.H
@@ -1,7 +1,7 @@
 //
 // Box header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2023 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -26,26 +26,51 @@
 #endif
 
 /**
-  This widget simply draws its box, and possibly its label.  Putting it
-  before some other widgets and making it big enough to surround them
-  will let you draw a frame around them.
+  This widget simply draws its box, and possibly its label.
+
+  Putting it before some other widgets and making it big enough to surround
+  them will let you draw a frame around them.
 */
 class FL_EXPORT Fl_Box : public Fl_Widget {
 protected:
   void draw() FL_OVERRIDE;
 public:
   /**
-    - The first constructor sets box() to FL_NO_BOX, which means it is invisible.
-      However such widgets are useful as placeholders or Fl_Group::resizable()
-      values. To change the box to something visible, use box(n).
-    - The second form of the constructor sets the box to the specified box type.
+    Creates a new Fl_Box widget with the given coordinates, size, and label.
+
+    This constructor sets box() to FL_NO_BOX, which means it is invisible.
+
+    However such widgets are useful as placeholders or Fl_Group::resizable()
+    values. To change the box to something visible, use box(Fl_Boxtype).
 
-    The destructor removes the box.
+    The destructor removes the box from its parent group.
+
+    \param[in] X, Y the position of the widget relative to the enclosing window
+    \param[in] W, H size of the widget in pixels
+    \param[in] L    optional text for the widget label (default: no label)
+
+    \see Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *L)
   */
-  Fl_Box(int X, int Y, int W, int H, const char *l=0);
+  Fl_Box(int X, int Y, int W, int H, const char *L = 0);
+
+  /**
+    Creates a new Fl_Box widget with the given boxtype, coordinates, size, and label.
+
+    This constructor sets box() to the given Fl_Boxtype \c B.
+
+    You must also specify a label but it can be \c nullptr (0, NULL) if you
+    don't want or need a visible label.
 
-  /**    See Fl_Box::Fl_Box(int x, int y, int w, int h, const char * = 0)   */
-  Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *l);
+    The destructor removes the box from its parent group.
+
+    \param[in] B    boxtype of the widget
+    \param[in] X, Y the position of the widget relative to the enclosing window
+    \param[in] W, H size of the widget in pixels
+    \param[in] L    optional text for the widget label (see description)
+
+    \see Fl_Box(int X, int Y, int W, int H, const char *L)
+  */
+  Fl_Box(Fl_Boxtype B, int X, int Y, int W, int H, const char *L);
 
   int handle(int) FL_OVERRIDE;
 };