1 files changed, 38 insertions, 14 deletions

diff --git a/FL/Fl_Pack.H b/FL/Fl_Pack.H
index 6a7e2be0d..26c5a33a7 100644
--- a/FL/Fl_Pack.H
+++ b/FL/Fl_Pack.H
@@ -3,17 +3,17 @@
 //
 // Pack header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2020 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
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
 /* \file
@@ -27,18 +27,31 @@
 /**
   This widget was designed to add the functionality of compressing and
   aligning widgets.
-  <P>If type() is Fl_Pack::HORIZONTAL all the children are
+
+  If type() is Fl_Pack::HORIZONTAL all the children are
   resized to the height of the Fl_Pack, and are moved next to
   each other horizontally. If type() is not Fl_Pack::HORIZONTAL
   then the children are resized to the width and are stacked below each
-  other.  Then the Fl_Pack resizes itself to surround the child
-  widgets.
-  <P>This widget is needed for the Fl_Tabs.
-  In addition you may want to put the Fl_Pack inside an 
-  Fl_Scroll.
-
-  <P>The resizable for Fl_Pack is set to NULL by default.</p>
-  <P>See also: Fl_Group::resizable()
+  other.  Then the Fl_Pack resizes itself to surround the child widgets.
+
+  You may want to put the Fl_Pack inside an Fl_Scroll.
+
+  The \p 'resizable()' for Fl_Pack is set to NULL by default. Its behavior
+  is slightly different than in a normal Fl_Group widget: only if the
+  resizable() widget is the last widget in the group it is extended to take
+  the full available width or height, respectively, of the Fl_Pack group.
+
+  \note You can nest Fl_Pack widgets or put them inside Fl_Scroll widgets
+    or inside other group widgets but their behavior can sometimes be
+    <i>"surprising"</i>. This is partly due to the fact that Fl_Pack widgets
+    resize themselves during their draw() operation, trying to react on
+    their child widgets resizing themselves during \b their draw() operations
+    which can be confusing. If you want to achieve special resize behavior
+    of nested group widgets it can sometimes be easier to derive your own
+    specialized group widget than to try to make nested Fl_Pack widgets
+    behave as expected.
+
+  \see Fl_Group::resizable()
 */
 class FL_EXPORT Fl_Pack : public Fl_Group {
   int spacing_;
@@ -53,7 +66,7 @@ protected:
   void draw();
 
 public:
-  Fl_Pack(int x,int y,int w ,int h,const char *l = 0);
+  Fl_Pack(int X, int Y, int W, int H, const char *L = 0);
   /**
     Gets the number of extra pixels of blank space that are added
     between the children.
@@ -64,7 +77,18 @@ public:
     between the children.
   */
   void spacing(int i) {spacing_ = i;}
-  /** Same as Fl_Group::type() */
+  /** Returns non-zero if Fl_Pack alignment is horizontal.
+
+    \returns non-zero if Fl_Pack alignment is horizontal (Fl_Pack::HORIZONTAL)
+
+    \note Currently the return value is the same as Fl_Group::type(), but
+      this may change in the future. Do not set any other values than the
+      following with Fl_Pack::type():
+      - Fl_Pack::VERTICAL (Default)
+      - Fl_Pack::HORIZONTAL
+
+    See class Fl_Pack documentation for details.
+  */
   uchar horizontal() const {return type();}
 };