FLUID: docs, testing

3 files changed, 26 insertions, 8 deletions

diff --git a/fluid/Fl_Type.cxx b/fluid/Fl_Type.cxx
index 4732b00e0..8c4120d94 100644
--- a/fluid/Fl_Type.cxx
+++ b/fluid/Fl_Type.cxx
@@ -238,7 +238,12 @@ static void delete_children(Fl_Type *p) {
   }
 }
 
-// object list operations:
+/** Delete all nodes in the Types tree and reset project settings, or delete selected nodes.
+ Also calls the browser to refresh.
+ \note Please refactor this into two separate methods of Fluid_Project.
+ \param[in] selected_only if set, delete only the selected widgets and
+ don't reset the project.
+ */
 void delete_all(int selected_only) {
   for (Fl_Type *f = Fl_Type::first; f;) {
     if (f->selected || !selected_only) {
@@ -268,8 +273,14 @@ void delete_all(int selected_only) {
   widget_browser->redraw();
 }
 
-// update a string member:
-// replace a string pointer with new value, strips leading/trailing blanks:
+/** Update a string.
+ Replace a string pointer with new value, strips leading/trailing blanks.
+ As a side effect, this call also sets the mod flags.
+ \param[in] n new string, can be NULL
+ \param[out] p update this pointer, possibly reallocate memory
+ \param[in] nostrip if set, do not strip leading and trailing spaces and tabs
+ \return 1 if the string in p changed
+ */
 int storestring(const char *n, const char * & p, int nostrip) {
   if (n == p) return 0;
   undo_checkpoint();
@@ -295,7 +306,10 @@ int storestring(const char *n, const char * & p, int nostrip) {
   return 1;
 }
 
-void fixvisible(Fl_Type *p) {
+/** Update the `visible` flag for `p` and all its descendants.
+ \param[in] p start here and update all descendants
+ */
+void update_visibility_flag(Fl_Type *p) {
   Fl_Type *t = p;
   for (;;) {
     if (t->parent) t->visible = t->parent->visible && t->parent->open_;
@@ -482,7 +496,7 @@ void Fl_Type::add(Fl_Type *p, Strategy strategy) {
   // tell this that it was added, so it can update itself
   if (p) p->add_child(this,0);
   open_ = 1;
-  fixvisible(this);
+  update_visibility_flag(this);
   set_modflag(1);
 
   if (strategy==kAddAfterCurrent && current) {
@@ -528,7 +542,7 @@ void Fl_Type::insert(Fl_Type *g) {
   if (prev) prev->next = this; else first = this;
   end->next = g;
   g->prev = end;
-  fixvisible(this);
+  update_visibility_flag(this);
   // tell parent that it has a new child, so it can update itself
   if (parent) parent->add_child(this, g);
   widget_browser->redraw();
diff --git a/fluid/Fl_Type.h b/fluid/Fl_Type.h
index ec30e5735..0d9a97848 100644
--- a/fluid/Fl_Type.h
+++ b/fluid/Fl_Type.h
@@ -34,7 +34,7 @@ typedef enum {
   kAddAfterCurrent
 } Strategy;
 
-void fixvisible(Fl_Type *p);
+void update_visibility_flag(Fl_Type *p);
 void delete_all(int selected_only=0);
 int storestring(const char *n, const char * & p, int nostrip=0);
 
@@ -93,7 +93,11 @@ public: // things that should not be public:
 
   /** Quick link to the parent Type instead of walking up the linked list. */
   Fl_Type *parent;
+  /** This type is rendered "selected" in the tree browser. */
   char new_selected; // browser highlight
+  /** Backup storage for selection if an error accured during some operation
+   (see `haderror`). It seems that this is often confused with new_selected
+   which seems to hold the true and visible selection state. */
   char selected; // copied here by selection_changed()
   char open_;   // state of triangle in browser
   char visible; // true if all parents are open
diff --git a/fluid/widget_browser.cxx b/fluid/widget_browser.cxx
index b7f95ba62..afc24f961 100644
--- a/fluid/widget_browser.cxx
+++ b/fluid/widget_browser.cxx
@@ -110,7 +110,7 @@ void reveal_in_browser(Fl_Type *t) {
       if (!p->parent) break;
       p = p->parent;
     }
-    fixvisible(p);
+    update_visibility_flag(p);
   }
   widget_browser->display(t);
   widget_browser->redraw();