Clarify and improve Fl::scheme() related documentation

2 files changed, 41 insertions, 29 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 506dc34ce..8f1e0bf44 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -14,9 +14,9 @@
 //     https://www.fltk.org/bugs.php
 //
 
-/** \file
-    Fl static class.
- */
+/** \file FL/Fl.H
+  \brief Fl static class.
+*/
 
 #ifndef Fl_H
 #  define Fl_H
@@ -425,12 +425,9 @@ public:
   static int is_scheme(const char *name) {
     return (scheme_ && name && !strcmp(name,scheme_));
   }
-  /**
-    Called by scheme according to scheme name.
-    Loads or reloads the current scheme selection.
-    See void scheme(const char *name)
-  */
-  static int reload_scheme(); // platform dependent
+
+  static int reload_scheme(); // defined in 'src/Fl_get_system_colors.cxx'
+
   static int scrollbar_size();
   static void scrollbar_size(int W);
   static int menu_linespacing();
diff --git a/src/Fl_get_system_colors.cxx b/src/Fl_get_system_colors.cxx
index 6e7d37214..6e9f5249e 100644
--- a/src/Fl_get_system_colors.cxx
+++ b/src/Fl_get_system_colors.cxx
@@ -132,32 +132,37 @@ static Fl_Pixmap        tile(tile_xpm);
 
 
 /**
-    Sets the current widget scheme. NULL will use the scheme defined
-    in the FLTK_SCHEME environment variable or the scheme resource
-    under X11. Otherwise, any of the following schemes can be used:
+  Sets the current widget scheme. NULL will use the scheme defined
+  in the FLTK_SCHEME environment variable or the scheme resource
+  under X11. Otherwise, any of the following schemes can be used:
 
-        - "none" - This is the default look-n-feel which resembles old
-                   Windows (95/98/Me/NT/2000) and old GTK/KDE
+    - "none" - This is the default look-n-feel which resembles old
+               Windows (95/98/Me/NT/2000) and old GTK/KDE
 
-        - "base" - This is an alias for "none"
+    - "base" - This is an alias for "none"
 
-        - "plastic" - This scheme is inspired by the Aqua user interface
-                      on Mac OS X
+    - "plastic" - This scheme is inspired by the Aqua user interface
+                  on macOS
 
-        - "gtk+" - This scheme is inspired by the Red Hat Bluecurve theme
+    - "gtk+" - This scheme is inspired by the Red Hat Bluecurve theme
 
-        - "gleam" - This scheme is inspired by the Clearlooks Glossy scheme.
-                    (Colin Jones and Edmanuel Torres).
+    - "gleam" - This scheme is inspired by the Clearlooks Glossy scheme.
+                (Colin Jones and Edmanuel Torres).
 
-        - "oxy" - Subset of Dmitrij K's oxy scheme (STR 2675, 3477)
+    - "oxy" - This is a subset of Dmitrij K's oxy scheme (STR 2675, 3477)
 
-    Uppercase scheme names are equivalent, but the stored scheme name will
-    always be lowercase and Fl::scheme() will return this lowercase name.
+  If the given scheme name is unknown, the default scheme will be used.
 
-    If the resulting scheme name is not defined, the default scheme will
-    be used and Fl::scheme() will return NULL.
+  Setting the scheme (name) is case insensitive, but the stored scheme name will
+  always be lowercase and Fl::scheme() will return this lowercase name or
+  \p NULL if no scheme or the default scheme ("none" or "base") was set.
 
-    \see Fl::is_scheme()
+  \param[in]  s   Scheme name of NULL
+
+  \returns    Current scheme name or NULL
+  \retval     NULL if the scheme has not been set or is the default scheme
+
+  \see Fl::is_scheme()
 */
 int Fl::scheme(const char *s) {
   if (!s) {
@@ -186,7 +191,17 @@ int Fl::scheme(const char *s) {
   return reload_scheme();
 }
 
+/**
+  Called internally when setting a new scheme according to scheme name.
+  Loads or reloads the current scheme selection.
+
+  \return   Always 1 (this may change in the future)
+
+  See void Fl::scheme(const char *name)
 
+  \internal
+  \note Internal: Should this method be private?
+*/
 int Fl::reload_scheme() {
   Fl_Window *win;
 
@@ -195,13 +210,13 @@ int Fl::reload_scheme() {
     uchar r, g, b;
     int nr, ng, nb;
     int i;
-//    static uchar levels[3] = { 0xff, 0xef, 0xe8 };
+    // static uchar levels[3] = { 0xff, 0xef, 0xe8 };
     // OSX 10.3 and higher use a background with less contrast...
     static uchar levels[3] = { 0xff, 0xf8, 0xf4 };
 
     get_color(FL_GRAY, r, g, b);
 
-//    printf("FL_GRAY = 0x%02x 0x%02x 0x%02x\n", r, g, b);
+    // printf("FL_GRAY = 0x%02x 0x%02x 0x%02x\n", r, g, b);
 
     for (i = 0; i < 3; i ++) {
       nr = levels[i] * r / 0xe8;
@@ -214,7 +229,7 @@ int Fl::reload_scheme() {
       if (nb > 255) nb = 255;
 
       snprintf(tile_cmap[i], sizeof(tile_cmap[0]), "%c c #%02x%02x%02x", "Oo."[i], nr, ng, nb);
-//      puts(tile_cmap[i]);
+      // puts(tile_cmap[i]);
     }
 
     tile.uncache();