From e8461a6191e0afa5fd96290856d1a056437469d0 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Thu, 10 Mar 2022 19:06:46 +0100
Subject: Document Fl::set_font(Fl_Font, const char *) with platform-specific
 details.

---
 src/fl_set_font.cxx | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/src/fl_set_font.cxx b/src/fl_set_font.cxx
index 6e68d466d..8243b7d06 100644
--- a/src/fl_set_font.cxx
+++ b/src/fl_set_font.cxx
@@ -29,8 +29,18 @@ extern FL_EXPORT Fl_Fontdesc *fl_fonts; // the table
 
 static int table_size;
 /**
-  Changes a face.  The string pointer is simply stored,
-  the string is not copied, so the string must be in static memory.
+  Changes a face.
+ \param fnum The font number to be assigned a new face
+ \param name Name of the font to assign. The string pointer is simply stored,
+ the string is not copied, so the string must be in static memory. The exact name to be used
+ depends on the platform :
+ 
+ \li Windows, X11, Xft: use the family name prefixed by one character to indicate the desired font variant.
+ Characters <tt>' ', 'I', 'B', 'P' </tt>denote plain, italic, bold, and bold-italic variants, respectively. For example,
+ string \c "IGabriola" is to be used to denote the <tt>"Gabriola italic"</tt> font. The \c "Oblique" suffix,
+ in whatever case, is to be treated  as \c "italic", that is, prefix the family name with \c 'I'.
+ \li Other platforms, i.e., X11 + Pango, Wayland, macOS: use the full font name as returned by
+ function Fl::get_font_name() or as listed by applications test/fonts or test/utf8. No prefix is to be added.
 */
 void Fl::set_font(Fl_Font fnum, const char* name) {
   Fl_Graphics_Driver &d = Fl_Graphics_Driver::default_driver();
-- 
cgit v1.2.3