Clarify documentation (STR 3532)

Make clear that Fl::repeat_timeout() must only be called for the
same timeout it is handling. Related STR's:

https://www.fltk.org/str.php?L3532
https://www.fltk.org/str.php?L3516

1 files changed, 16 insertions, 13 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 405eba47b..3c4a0f011 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -473,22 +473,25 @@ int main() {
   static void add_timeout(double t, Fl_Timeout_Handler,void* = 0); // platform dependent
   /**
   Repeats a timeout callback from the expiration of the
-  previous timeout, allowing for more accurate timing. You may only call
-  this method inside a timeout callback.
-  
+  previous timeout, allowing for more accurate timing.
+
+  You may only call this method inside a timeout callback of the same timer
+  or at least a closely related timer, otherwise the timing accuracy can't
+  be improved and the behavior is undefined.
+
   The following code will print "TICK" each second on
   stdout with a fair degree of accuracy:
-  
+
   \code
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
+    void callback(void*) {
+      puts("TICK");
+      Fl::repeat_timeout(1.0, callback);
+    }
+
+    int main() {
+      Fl::add_timeout(1.0, callback);
+      return Fl::run();
+    }
   \endcode
   */
   static void repeat_timeout(double t, Fl_Timeout_Handler, void* = 0); // platform dependent