From b95a7eccd939fd3482604fdd9f56be3c6168bfcd Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Wed, 28 Aug 2024 10:05:17 +0200
Subject: [PATCH] Fix Doxygen problems with fl_draw() functions.

---
 FL/fl_draw.H                  | 37 +++++++++++++++++++++++++++++++
 documentation/src/drawing.dox |  4 ++--
 src/fl_draw.cxx               | 41 ++++-------------------------------
 3 files changed, 43 insertions(+), 39 deletions(-)

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index efb0b4d15..f5575e950 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -975,9 +975,46 @@ inline void fl_rtl_draw(const char *str, int n, int x, int y) {
   fl_graphics_driver->rtl_draw(str, n, x, y);
 }
 FL_EXPORT void fl_measure(const char *str, int &x, int &y, int draw_symbols = 1);
+/**
+  Fancy string drawing function which is used to draw all the labels.
+
+  The string is formatted and aligned inside the passed box.
+  Handles '\\t' and '\\n', expands all other control characters to '^X',
+  and aligns inside or against the edges of the box.
+  See Fl_Widget::align() for values of \p align. The value FL_ALIGN_INSIDE
+  is ignored, as this function always prints inside the box.
+  If \p img is provided and is not \p NULL, the image is drawn above or
+  below the text as specified by the \p align value.
+  The \p draw_symbols argument specifies whether or not to look for symbol
+  names starting with the '\@' character'
+
+ \param[in] str UTF-8 string, can start and end with an '\@sym' symbol,
+            can contain '\\n'
+ \param[in] x,y,w,h bounding box
+ \param[in] align label and image alignment in bounding box
+ \param[in] img pointer to image
+ \param[in] draw_symbols if true, interprete leading and trailing '\@sym'
+            as graphical symbols
+ \param[in] spacing spacing between text and image
+ */
 FL_EXPORT void fl_draw(const char *str, int x, int y, int w, int h, 
                        Fl_Align align, Fl_Image *img = 0,
                        int draw_symbols = 1, int spacing = 0);
+/**
+ The same as fl_draw(const char*,int,int,int,int,Fl_Align,Fl_Image*,int) with
+ the addition of the \p callthis parameter, which is a pointer to a text drawing
+ function such as fl_draw(const char*, int, int, int) to do the real work.
+
+ \param[in] str UTF-8 string, can start and end with an '\@sym' symbol,
+ can contain '\\n'
+ \param[in] x,y,w,h bounding box
+ \param[in] align label and image alignment in bounding box
+ \param[in] callthis pointer to text drawing function
+ \param[in] img pointer to image
+ \param[in] draw_symbols if true, interprete leading and trailing '\@sym'
+ as graphical symbols
+ \param[in] spacing spacing between text and image
+ */
 FL_EXPORT void fl_draw(const char *str, int x, int y, int w, int h, Fl_Align align,
                        void (*callthis)(const char *, int, int, int),
                        Fl_Image *img = 0, int draw_symbols = 1, int spacing = 0);
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 13fc9262c..42f313e51 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -775,7 +775,7 @@ void fl_rtl_draw(const char *str, int n, int x, int y)
 \par
 Draw a UTF-8 string of length n bytes right to left starting at the given x, y location.
 
-void fl_draw(const char* str, int x, int y, int w, int h, Fl_Align align, Fl_Image* img, int draw_symbols)
+void fl_draw(const char* str, int x, int y, int w, int h, Fl_Align align, Fl_Image* img, int draw_symbols, int spacing)
 
 \par
 Fancy string drawing function which is used to draw all the
@@ -785,7 +785,7 @@ characters to ^X, and aligns inside or against the edges of the
 box described by \p x, \p y, \p w and \p h.
 See Fl_Widget::align() for values for \p align.
 The value \p FL_ALIGN_INSIDE is ignored, as this function always
-prints inside the box.
+prints inside the box. Parameter \p spacing controls the space between text and image.
 
 \par
 If \p img is provided and is not \p NULL, the
diff --git a/src/fl_draw.cxx b/src/fl_draw.cxx
index 7f1b941ef..72823b078 100644
--- a/src/fl_draw.cxx
+++ b/src/fl_draw.cxx
@@ -189,21 +189,8 @@ fl_expand_text(const char* from, char* buf, int maxbuf, double maxw, int& n,
   return expand_text_(from,  buf, maxbuf, maxw,  n, width,  wrap,  draw_symbols);
 }
 
-/**
- The same as fl_draw(const char*,int,int,int,int,Fl_Align,Fl_Image*,int) with
- the addition of the \p callthis parameter, which is a pointer to a text drawing
- function such as fl_draw(const char*, int, int, int) to do the real work.
-
- \param[in] str UTF-8 string, can start and end with an '\@sym' symbol,
- can contain '\\n'
- \param[in] x,y,w,h bounding box
- \param[in] align label and image alignment in bounding box
- \param[in] callthis pointer to text drawing function
- \param[in] img pointer to image
- \param[in] draw_symbols if true, interprete leading and trailing '\@sym'
- as graphical symbols
- \param[in] spacing spacing between text and image
- */
+// Caution: put the documentation next to the function's declaration in fl_draw.H for Doxygen
+// to see default argument values.
 void fl_draw(
     const char* str,    // the (multi-line) string
     int x, int y, int w, int h, // bounding box
@@ -448,28 +435,8 @@ void fl_draw(
   }
 }
 
-/**
-  Fancy string drawing function which is used to draw all the labels.
-
-  The string is formatted and aligned inside the passed box.
-  Handles '\\t' and '\\n', expands all other control characters to '^X',
-  and aligns inside or against the edges of the box.
-  See Fl_Widget::align() for values of \p align. The value FL_ALIGN_INSIDE
-  is ignored, as this function always prints inside the box.
-  If \p img is provided and is not \p NULL, the image is drawn above or
-  below the text as specified by the \p align value.
-  The \p draw_symbols argument specifies whether or not to look for symbol
-  names starting with the '\@' character'
-
- \param[in] str UTF-8 string, can start and end with an '\@sym' symbol,
-            can contain '\\n'
- \param[in] x,y,w,h bounding box
- \param[in] align label and image alignment in bounding box
- \param[in] img pointer to image
- \param[in] draw_symbols if true, interprete leading and trailing '\@sym'
-            as graphical symbols
- \param[in] spacing spacing between text and image
- */
+// Caution: put the documentation next to the function's declaration in fl_draw.H for Doxygen
+// to see default argument values.
 void fl_draw(
   const char* str,
   int x, int y, int w, int h,