FLUDI documentation updates

3 files changed, 268 insertions, 25 deletions

diff --git a/fluid/Fd_Snap_Action.cxx b/fluid/Fd_Snap_Action.cxx
index 7a4338ec6..4c9be9b2b 100644
--- a/fluid/Fd_Snap_Action.cxx
+++ b/fluid/Fd_Snap_Action.cxx
@@ -145,6 +145,9 @@ void edit_layout_preset_cb(Fl_Button *w, long user_data) {
 
 // ---- Fd_Layout_Suite ------------------------------------------------ MARK: -
 
+/**
+ Write presets to a Preferences database.
+ */
 void Fd_Layout_Preset::write(Fl_Preferences &prefs) {
   assert(this);
   Fl_Preferences p_win(prefs, "Window");
@@ -182,6 +185,9 @@ void Fd_Layout_Preset::write(Fl_Preferences &prefs) {
   p_lyt.set("textsize", textsize);
 }
 
+/**
+ Read presets from a Preferences database.
+ */
 void Fd_Layout_Preset::read(Fl_Preferences &prefs) {
   assert(this);
   Fl_Preferences p_win(prefs, "Window");
@@ -219,6 +225,9 @@ void Fd_Layout_Preset::read(Fl_Preferences &prefs) {
   p_lyt.get("textsize", textsize, 14);
 }
 
+/**
+ Write presets to an .fl project file.
+ */
 void Fd_Layout_Preset::write(Fd_Project_Writer *out) {
   out->write_string("    preset { 1\n"); // preset format version
   out->write_string("      %d %d %d %d %d %d\n",
@@ -238,6 +247,9 @@ void Fd_Layout_Preset::write(Fd_Project_Writer *out) {
   out->write_string("    }\n"); // preset format version
 }
 
+/**
+ Read presets from an .fl project file.
+ */
 void Fd_Layout_Preset::read(Fd_Project_Reader *in) {
   const char *key;
   key = in->read_word(1);
@@ -294,6 +306,9 @@ void Fd_Layout_Preset::read(Fd_Project_Reader *in) {
 
 // ---- Fd_Layout_Suite ------------------------------------------------ MARK: -
 
+/**
+ Write a presets suite to a Preferences database.
+ */
 void Fd_Layout_Suite::write(Fl_Preferences &prefs) {
   assert(this);
   assert(name_);
@@ -305,6 +320,9 @@ void Fd_Layout_Suite::write(Fl_Preferences &prefs) {
   }
 }
 
+/**
+ Read a presets suite from a Preferences database.
+ */
 void Fd_Layout_Suite::read(Fl_Preferences &prefs) {
   assert(this);
   for (int i = 0; i < 3; ++i) {
@@ -314,6 +332,9 @@ void Fd_Layout_Suite::read(Fl_Preferences &prefs) {
   }
 }
 
+/**
+ Write a presets suite to an .fl project file.
+ */
 void Fd_Layout_Suite::write(Fd_Project_Writer *out) {
   out->write_string("  suite {\n");
   out->write_string("    name "); out->write_word(name_); out->write_string("\n");
@@ -323,6 +344,9 @@ void Fd_Layout_Suite::write(Fd_Project_Writer *out) {
   out->write_string("  }\n");
 }
 
+/**
+ Read a presets suite from an .fl project file.
+ */
 void Fd_Layout_Suite::read(Fd_Project_Reader *in) {
   const char *key;
   key = in->read_word(1);
@@ -347,6 +371,10 @@ void Fd_Layout_Suite::read(Fd_Project_Reader *in) {
   }
 }
 
+/**
+ \brief Update the menu_label to show a symbol representing the storage location.
+ Also updates the FLUID user interface.
+ */
 void Fd_Layout_Suite::update_label() {
   Fl_String sym;
   switch (storage_) {
@@ -362,6 +390,10 @@ void Fd_Layout_Suite::update_label() {
   g_layout_list.update_menu_labels();
 }
 
+/**
+ \brief Update the Suite name and the Suite menu_label.
+ Also updates the FLUID user interface.
+ */
 void Fd_Layout_Suite::name(const char *n) {
   if (name_)
     ::free(name_);
@@ -372,6 +404,9 @@ void Fd_Layout_Suite::name(const char *n) {
   update_label();
 }
 
+/**
+ Initialise the class for first use.
+ */
 void Fd_Layout_Suite::init() {
   name_ = NULL;
   menu_label = NULL;
@@ -379,6 +414,9 @@ void Fd_Layout_Suite::init() {
   storage_ = 0;
 }
 
+/**
+ Free all allocated resources.
+ */
 Fd_Layout_Suite::~Fd_Layout_Suite() {
   if (storage_ == FD_STORE_INTERNAL) return;
   if (name_) ::free(name_);
@@ -389,6 +427,9 @@ Fd_Layout_Suite::~Fd_Layout_Suite() {
 
 // ---- Fd_Layout_List ------------------------------------------------- MARK: -
 
+/**
+ Draw a little FLUID beaker symbol.
+ */
 static void fd_beaker(Fl_Color c) {
   fl_color(221);
   fl_begin_polygon();
@@ -414,6 +455,9 @@ static void fd_beaker(Fl_Color c) {
   fl_end_line();
 }
 
+/**
+ Draw a user silhouette symbol
+ */
 static void fd_user(Fl_Color c) {
   fl_color(245);
   fl_begin_complex_polygon();
@@ -429,6 +473,9 @@ static void fd_user(Fl_Color c) {
   fl_end_line();
 }
 
+/**
+ Draw a document symbol.
+ */
 static void fd_project(Fl_Color c) {
   Fl_Color fc = FL_LIGHT2;
   fl_color(fc);
@@ -464,6 +511,9 @@ static void fd_project(Fl_Color c) {
   fl_end_line();
 }
 
+/**
+ Draw a 3 1/2" floppy symbol.
+ */
 void fd_file(Fl_Color c) {
   Fl_Color fl = FL_LIGHT2;
   Fl_Color fc = FL_DARK3;
@@ -515,7 +565,9 @@ void fd_file(Fl_Color c) {
   fl_end_loop();
 }
 
-
+/**
+ Instantiate the class that holds a list of all layouts and manages the UI.
+ */
 Fd_Layout_List::Fd_Layout_List()
 : main_menu_(main_layout_submenu_),
   choice_menu_(static_choice_menu),
@@ -533,6 +585,9 @@ Fd_Layout_List::Fd_Layout_List()
   fl_add_symbol("fd_file", fd_file, 1);
 }
 
+/**
+ Release allocated resources.
+ */
 Fd_Layout_List::~Fd_Layout_List() {
   assert(this);
   if (!list_is_static_) {
@@ -548,6 +603,9 @@ Fd_Layout_List::~Fd_Layout_List() {
   if (filename_) ::free(filename_);
 }
 
+/**
+ Update the Setting dialog and menus to reflect the current Layout selection state.
+ */
 void Fd_Layout_List::update_dialogs() {
   static Fl_Menu_Item *preset_menu = NULL;
   if (!preset_menu) {
@@ -569,6 +627,9 @@ void Fd_Layout_List::update_dialogs() {
   main_menu_[current_suite_].setonly(main_menu_);
 }
 
+/**
+ Refresh the label pointers for both pulldown menus.
+ */
 void Fd_Layout_List::update_menu_labels() {
   for (int i=0; i<list_size_; i++) {
     main_menu_[i].label(list_[i].menu_label);
@@ -576,6 +637,9 @@ void Fd_Layout_List::update_menu_labels() {
   }
 }
 
+/**
+ Load all user layouts from the FLUID user preferences.
+ */
 int Fd_Layout_List::load(const char *filename) {
   remove_all(FD_STORE_FILE);
   Fl_Preferences prefs(filename, "layout.fluid.fltk.org", NULL);
@@ -583,6 +647,9 @@ int Fd_Layout_List::load(const char *filename) {
   return 0;
 }
 
+/**
+ Save all user layouts to the FLUID user preferences.
+ */
 int Fd_Layout_List::save(const char *filename) {
   assert(this);
   assert(filename);
@@ -592,6 +659,9 @@ int Fd_Layout_List::save(const char *filename) {
   return 0;
 }
 
+/**
+ Write Suite and Layout selection and selected layout data to Preferences database.
+ */
 void Fd_Layout_List::write(Fl_Preferences &prefs, int storage) {
   Fl_Preferences prefs_list(prefs, "Layouts");
   prefs_list.clear();
@@ -607,6 +677,9 @@ void Fd_Layout_List::write(Fl_Preferences &prefs, int storage) {
   }
 }
 
+/**
+ Read Suite and Layout selection and selected layout data to Preferences database.
+ */
 void Fd_Layout_List::read(Fl_Preferences &prefs, int storage) {
   Fl_Preferences prefs_list(prefs, "Layouts");
   Fl_String cs;
@@ -629,6 +702,9 @@ void Fd_Layout_List::read(Fl_Preferences &prefs, int storage) {
   update_dialogs();
 }
 
+/**
+ Write Suite and Layout selection and project layout data to an .fl project file.
+ */
 void Fd_Layout_List::write(Fd_Project_Writer *out) {
   out->write_string("\nsnap {\n  ver 1\n");
   out->write_string("  current_suite "); out->write_word(list_[current_suite()].name_); out->write_string("\n");
@@ -641,6 +717,9 @@ void Fd_Layout_List::write(Fd_Project_Writer *out) {
   out->write_string("}");
 }
 
+/**
+ Read Suite and Layout selection and project layout data from an .fl project file.
+ */
 void Fd_Layout_List::read(Fd_Project_Reader *in) {
   const char *key;
   key = in->read_word(1);
@@ -674,6 +753,10 @@ void Fd_Layout_List::read(Fd_Project_Reader *in) {
   }
 }
 
+/**
+ Set the current Suite.
+ \param[in] ix index into list of suites
+ */
 void Fd_Layout_List::current_suite(int ix) {
   assert(ix >= 0);
   assert(ix < list_size_);
@@ -681,6 +764,11 @@ void Fd_Layout_List::current_suite(int ix) {
   layout = list_[current_suite_].layout[current_preset_];
 }
 
+/**
+ Set the current Suite.
+ \param[in] arg_name name of the selected suite
+ \return if no name is given or the name is not found, keep the current suite selected
+ */
 void Fd_Layout_List::current_suite(Fl_String arg_name) {
   if (arg_name.empty()) return;
   for (int i = 0; i < list_size_; ++i) {
@@ -692,6 +780,10 @@ void Fd_Layout_List::current_suite(Fl_String arg_name) {
   }
 }
 
+/**
+ Select a Preset within the current Suite.
+ \param[in] ix 0 = application, 1 = dialog, 2 = toolbox
+ */
 void Fd_Layout_List::current_preset(int ix) {
   assert(ix >= 0);
   assert(ix < 3);
@@ -735,7 +827,7 @@ void Fd_Layout_List::capacity(int n) {
 }
 
 /**
- Clone the currently selected suite and append it to the list.
+ \brief Clone the currently selected suite and append it to the list.
  Selectes the new layout and updates the UI.
  */
 int Fd_Layout_List::add(const char *name) {
@@ -765,6 +857,9 @@ int Fd_Layout_List::add(const char *name) {
   return n;
 }
 
+/**
+ Rename the current Suite.
+ */
 void Fd_Layout_List::rename(const char *name) {
   int n = current_suite();
   list_[n].name(name);
@@ -772,6 +867,10 @@ void Fd_Layout_List::rename(const char *name) {
   choice_menu_[n].label(list_[n].menu_label);
 }
 
+/**
+ Remove the given suite.
+ \param[in] ix index into list of suites
+ */
 void Fd_Layout_List::remove(int ix) {
   int tail = list_size_-ix-1;
   if (tail) {
@@ -785,6 +884,10 @@ void Fd_Layout_List::remove(int ix) {
     current_suite(list_size_ - 1);
 }
 
+/**
+ Remove all Suites that use the given storage attribute.
+ \param[in] storage storage attribute, see FD_STORE_INTERNAL, etc.
+ */
 void Fd_Layout_List::remove_all(int storage) {
   for (int i=list_size_-1; i>=0; --i) {
     if (list_[i].storage_ == storage)
@@ -830,8 +933,30 @@ static Fl_Group *parent(Fd_Snap_Data &d) {
 // ---- Fd_Snap_Action ------------------------------------------------- MARK: -
 
 /** \class Fd_Snap_Action
+
+ When a user drags one or more widgets, snap actions can be defined that provide
+ hints if a preferred widget position or size is nearby. The user's motion is
+ then directed towards the nearest preferred position, and the widget selection
+ snaps into place.
+
+ FLUID provides a list of various snap actions. Every snap action uses the data
+ from the motion event and combines it with the sizes and positions of all other
+ widgets in the layout.
+
+ Common snap actions include gaps and margins, but also alignments and
+ simple grid positions.
  */
 
+/**
+ \brief Check if a snap action has reached a preferred x position.
+ \param[inout] d current event data
+ \param[in] x_ref position of moving point
+ \param[in] x_snap position of target point
+ \return 1 if the points are not within range and won;t be considered
+ \return 0 if the point is as close as another in a prevoius action
+ \return -1 if this point is closer than any previous check, and this is the
+    new distance to beat.
+ */
 int Fd_Snap_Action::check_x_(Fd_Snap_Data &d, int x_ref, int x_snap) {
   int dd = x_ref + d.dx - x_snap;
   int d2 = abs(dd);
@@ -843,6 +968,10 @@ int Fd_Snap_Action::check_x_(Fd_Snap_Data &d, int x_ref, int x_snap) {
   return -1;
 }
 
+/**
+ \brief Check if a snap action has reached a preferred y position.
+ \see Fd_Snap_Action::check_x_(Fd_Snap_Data &d, int x_ref, int x_snap)
+ */
 int Fd_Snap_Action::check_y_(Fd_Snap_Data &d, int y_ref, int y_snap) {
   int dd = y_ref + d.dy - y_snap;
   int d2 = abs(dd);
@@ -854,6 +983,10 @@ int Fd_Snap_Action::check_y_(Fd_Snap_Data &d, int y_ref, int y_snap) {
   return -1;
 }
 
+/**
+ \brief Check if a snap action has reached a preferred x and y position.
+ \see Fd_Snap_Action::check_x_(Fd_Snap_Data &d, int x_ref, int x_snap)
+ */
 void Fd_Snap_Action::check_x_y_(Fd_Snap_Data &d, int x_ref, int x_snap, int y_ref, int y_snap) {
   int ddx = x_ref + d.dx - x_snap;
   int d2x = abs(ddx);
@@ -869,6 +1002,12 @@ void Fd_Snap_Action::check_x_y_(Fd_Snap_Data &d, int x_ref, int x_snap, int y_re
   }
 }
 
+/**
+ \brief Check if a snap action was applied to the current event.
+ This method is used to determine if a visual indicator for this snap action
+ should be drawn.
+ \param[inout] d current event data
+ */
 bool Fd_Snap_Action::matches(Fd_Snap_Data &d) {
   switch (type) {
     case 1: return (d.drag & mask) && (eex == ex) && (d.dx == dx);
@@ -878,6 +1017,10 @@ bool Fd_Snap_Action::matches(Fd_Snap_Data &d) {
   return false;
 }
 
+/**
+ \brief Run through all possible snap actions and store the winning coordinates in eex and eey.
+ \param[inout] d current event data
+ */
 void Fd_Snap_Action::check_all(Fd_Snap_Data &data) {
   for (int i=0; list[i]; i++) {
     if (list[i]->mask & data.drag)
@@ -887,6 +1030,13 @@ void Fd_Snap_Action::check_all(Fd_Snap_Data &data) {
   eey = data.ey_out;
 }
 
+/**
+ \brief Draw a visual indicator for all sanp actions that were applied during the last check.
+ Only one snap coordinate can win. FLUID chooses the one that is closest to
+ the current user event. If two or more snap actions suggest the same
+ coordinate, all of them will be drawn.
+ \param[inout] d current event data
+ */
 void Fd_Snap_Action::draw_all(Fd_Snap_Data &data) {
   for (int i=0; list[i]; i++) {
     if (list[i]->matches(data))
@@ -924,21 +1074,33 @@ void Fd_Snap_Action::get_move_stepsize(int &x_step, int &y_step) {
 
 // ---- snapping prototypes -------------------------------------------- MARK: -
 
+/**
+ Base class for all actions that drag the left side or the entire widget.
+ */
 class Fd_Snap_Left : public Fd_Snap_Action {
 public:
   Fd_Snap_Left() { type = 1; mask = FD_LEFT|FD_DRAG; }
 };
 
+/**
+ Base class for all actions that drag the right side or the entire widget.
+ */
 class Fd_Snap_Right : public Fd_Snap_Action {
 public:
   Fd_Snap_Right() { type = 1; mask = FD_RIGHT|FD_DRAG; }
 };
 
+/**
+ Base class for all actions that drag the top side or the entire widget.
+ */
 class Fd_Snap_Top : public Fd_Snap_Action {
 public:
   Fd_Snap_Top() { type = 2; mask = FD_TOP|FD_DRAG; }
 };
 
+/**
+ Base class for all actions that drag the bottom side or the entire widget.
+ */
 class Fd_Snap_Bottom : public Fd_Snap_Action {
 public:
   Fd_Snap_Bottom() { type = 2; mask = FD_BOTTOM|FD_DRAG; }
@@ -946,6 +1108,9 @@ public:
 
 // ---- window snapping ------------------------------------------------ MARK: -
 
+/**
+ Check if the widget hits the left window edge.
+ */
 class Fd_Snap_Left_Window_Edge : public Fd_Snap_Left {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE { clr(); check_x_(d, d.bx, 0); }
@@ -953,6 +1118,9 @@ public:
 };
 Fd_Snap_Left_Window_Edge snap_left_window_edge;
 
+/**
+ Check if the widget hits the right window edge.
+ */
 class Fd_Snap_Right_Window_Edge : public Fd_Snap_Right {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE { clr(); check_x_(d, d.br, d.win->o->w()); }
@@ -960,6 +1128,9 @@ public:
 };
 Fd_Snap_Right_Window_Edge snap_right_window_edge;
 
+/**
+ Check if the widget hits the top window edge.
+ */
 class Fd_Snap_Top_Window_Edge : public Fd_Snap_Top {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE { clr(); check_y_(d, d.by, 0); }
@@ -967,6 +1138,9 @@ public:
 };
 Fd_Snap_Top_Window_Edge snap_top_window_edge;
 
+/**
+ Check if the widget hits the bottom window edge.
+ */
 class Fd_Snap_Bottom_Window_Edge : public Fd_Snap_Bottom {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE { clr(); check_y_(d, d.bt, d.win->o->h()); }
@@ -974,6 +1148,9 @@ public:
 };
 Fd_Snap_Bottom_Window_Edge snap_bottom_window_edge;
 
+/**
+ Check if the widget hits the left window edge plus a user defined margin.
+ */
 class Fd_Snap_Left_Window_Margin : public Fd_Snap_Left {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1024,6 +1201,9 @@ Fd_Snap_Bottom_Window_Margin snap_bottom_window_margin;
 
 // ---- group snapping ------------------------------------------------- MARK: -
 
+/**
+ Check if the widget hits the left group edge.
+ */
 class Fd_Snap_Left_Group_Edge : public Fd_Snap_Left {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1073,6 +1253,9 @@ public:
 Fd_Snap_Bottom_Group_Edge snap_bottom_group_edge;
 
 
+/**
+ Check if the widget hits the left group edge plus a user defined margin.
+ */
 class Fd_Snap_Left_Group_Margin : public Fd_Snap_Left {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1127,6 +1310,9 @@ Fd_Snap_Bottom_Group_Margin snap_bottom_group_margin;
 
 // ----- tabs snapping ------------------------------------------------- MARK: -
 
+/**
+ Check if the widget top hits the Fl_Tabs group top edge plus a user defined margin.
+ */
 class Fd_Snap_Top_Tabs_Margin : public Fd_Snap_Top_Group_Margin {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1147,6 +1333,9 @@ Fd_Snap_Bottom_Tabs_Margin snap_bottom_tabs_margin;
 
 // ----- grid snapping ------------------------------------------------- MARK: -
 
+/**
+ Base class for grid based snapping.
+ */
 class Fd_Snap_Grid : public Fd_Snap_Action {
 protected:
   int nearest_x, nearest_y;
@@ -1172,6 +1361,9 @@ public:
   }
 };
 
+/**
+ Check if the widget hits window grid coordinates.
+ */
 class Fd_Snap_Window_Grid : public Fd_Snap_Grid {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1185,6 +1377,9 @@ public:
 };
 Fd_Snap_Window_Grid snap_window_grid;
 
+/**
+ Check if the widget hits group grid coordinates.
+ */
 class Fd_Snap_Group_Grid : public Fd_Snap_Grid {
 public:
   void check(Fd_Snap_Data &d) FL_OVERRIDE {
@@ -1203,6 +1398,9 @@ Fd_Snap_Group_Grid snap_group_grid;
 
 // ----- sibling snapping ---------------------------------------------- MARK: -
 
+/**
+ Base class the check distance to other widgets in the same group.
+ */
 class Fd_Snap_Sibling : public Fd_Snap_Action {
 protected:
   Fl_Widget *best_match;
@@ -1237,6 +1435,9 @@ public:
   }
 };
 
+/**
+ Check if widgets have the same x coordinate, so they can be vertically aligned.
+ */
 class Fd_Snap_Siblings_Left_Same : public Fd_Snap_Sibling {
 public:
   Fd_Snap_Siblings_Left_Same() { type = 1; mask = FD_LEFT|FD_DRAG; }
@@ -1249,6 +1450,9 @@ public:
 };
 Fd_Snap_Siblings_Left_Same snap_siblings_left_same;
 
+/**
+ Check if widgets touch left to right, or have a user selected gap left to right.
+ */
 class Fd_Snap_Siblings_Left : public Fd_Snap_Sibling {
 public:
   Fd_Snap_Siblings_Left() { type = 1; mask = FD_LEFT|FD_DRAG; }
@@ -1340,6 +1544,9 @@ Fd_Snap_Siblings_Bottom snap_siblings_bottom;
 
 // ------ widget snapping ---------------------------------------------- MARK: -
 
+/**
+ Snap horizontal resizing to min_w or min_w and a multiple of inc_w.
+ */
 class Fd_Snap_Widget_Ideal_Width : public Fd_Snap_Action {
 public:
   Fd_Snap_Widget_Ideal_Width() { type = 1; mask = FD_LEFT|FD_RIGHT; }
@@ -1394,6 +1601,13 @@ Fd_Snap_Widget_Ideal_Height snap_widget_ideal_height;
 
 // ---- snap actions list ---------------------------------------------- MARK: -
 
+/**
+ /brief The list of all snap actions availabel to FLUID.
+ New snap actions can be appended to the list. If multiple snap actions
+ with different corrdinates, but the same sanp distance are found, the last
+ action in the list wins. All snap actions with the same distance and same
+ winning coordinates are drawn in the overlay plane.
+ */
 Fd_Snap_Action *Fd_Snap_Action::list[] = {
   &snap_left_window_edge,
   &snap_right_window_edge,
diff --git a/fluid/Fd_Snap_Action.h b/fluid/Fd_Snap_Action.h
index 201ed497d..7ceec2731 100644
--- a/fluid/Fd_Snap_Action.h
+++ b/fluid/Fd_Snap_Action.h
@@ -23,43 +23,54 @@ struct Fl_Menu_Item;
 
 extern Fl_Menu_Item main_layout_submenu_[];
 
+/**
+ Indicate the storage location for a layout suite.
+ */
 enum {
-  FD_STORE_INTERNAL,
-  FD_STORE_USER,
-  FD_STORE_PROJECT,
-  FD_STORE_FILE
+  FD_STORE_INTERNAL,  ///< stored inside FLUID app
+  FD_STORE_USER,      ///< suite is stored in the user wide FLUID settings
+  FD_STORE_PROJECT,   ///< suite is stored within the current .fl project file
+  FD_STORE_FILE       ///< store suite in external file
 };
 
+/**
+ \brief Collection of layout settings.
+
+ Presets contain default fonts and font sizes for labels and text. They
+ can be used to guide widget positions usung margins, grids, and gap sizes.
+ There are three Presets available in one Suite, marked "application",
+ "dialog", and "toolbox".
+ */
 class Fd_Layout_Preset {
 public:
-  int left_window_margin;
+  int left_window_margin;   ///< gap between the window border and the widget
   int right_window_margin;
   int top_window_margin;
   int bottom_window_margin;
-  int window_grid_x;
+  int window_grid_x;        ///< a regular grid across the window with its origin in the top left window corner
   int window_grid_y;
 
-  int left_group_margin;
+  int left_group_margin;    ///< gap between the border of a widget and its parent group
   int right_group_margin;
   int top_group_margin;
   int bottom_group_margin;
-  int group_grid_x;
+  int group_grid_x;         ///< a regular grid across the group with its origin in the top left group corner
   int group_grid_y;
 
-  int top_tabs_margin;
-  int bottom_tabs_margin;
+  int top_tabs_margin;      ///< preferred top edge tab size inside Fl_Tabs
+  int bottom_tabs_margin;   ///< preferred bottom edge tab size inside Fl_Tabs
 
-  int widget_min_w;
-  int widget_inc_w;
-  int widget_gap_x;
+  int widget_min_w;         ///< minimum widget width
+  int widget_inc_w;         ///< widget width increments starting from widget_min_w
+  int widget_gap_x;         ///< preferred horizontal gap between widgets
   int widget_min_h;
   int widget_inc_h;
   int widget_gap_y;
 
-  int labelfont;
-  int labelsize;
-  int textfont;
-  int textsize;
+  int labelfont;            ///< preferred font for labels
+  int labelsize;            ///< preferred size for labels
+  int textfont;             ///< preferred font for text elements
+  int textsize;             ///< preferred size for text elements
 
   void write(Fl_Preferences &prefs);
   void read(Fl_Preferences &prefs);
@@ -69,12 +80,20 @@ public:
 
 extern Fd_Layout_Preset *layout;
 
+/**
+ \brief A collection of layout presets.
+
+ A suite of layout presets is designed to cover various use cases when
+ designing UI layouts for applications.
+ There are three Presets available in one Suite, marked "application",
+ "dialog", and "toolbox".
+ */
 class Fd_Layout_Suite {
 public:
-  char *name_;
-  char *menu_label;
-  Fd_Layout_Preset *layout[3]; // application, dialog, toolbox;
-  int storage_;
+  char *name_;                  ///< name of the suite
+  char *menu_label;             ///< label text used in pulldown menu
+  Fd_Layout_Preset *layout[3];  ///< presetes for application, dialog, and toolbox windows
+  int storage_;                 ///< storage location (see FD_STORE_INTERNAL, etc.)
   void write(Fl_Preferences &prefs);
   void read(Fl_Preferences &prefs);
   void write(Fd_Project_Writer*);
@@ -88,6 +107,13 @@ public:
 
 };
 
+/**
+ \brief Manage all layout suites that are available to the user.
+
+ FLUID has two built-in suites. More suites can be cloned or added and stored
+ as a user preference, as part of an .fl project file, or in a seperate file
+ for import/export and sharing.
+ */
 class Fd_Layout_List {
 public:
   Fl_Menu_Item *main_menu_;
diff --git a/fluid/Fl_Function_Type.cxx b/fluid/Fl_Function_Type.cxx
index 0a96326d5..22ced326b 100644
--- a/fluid/Fl_Function_Type.cxx
+++ b/fluid/Fl_Function_Type.cxx
@@ -34,8 +34,11 @@
 Fl_Class_Type *current_class = NULL;
 
 /**
- Return 1 if the list contains a function with the given signature at the top level.
- \param[in] rtype return type
+ \brief Return 1 if the list contains a function with the given signature at the top level.
+ Fl_Widget_Type uses this to check if a callback by a certain signature is
+ already defined by the user within this file. If not, Fl_Widget_Type will
+ generate an `extern $sig$;` statement.
+ \param[in] rtype return type, can be NULL to avoid checking (not used by Fl_Widget_Type)
  \param[in] sig function signature
  \return 1 if found.
  */