Added docs for public fl_vsnprintf() (STR #3413)

Applied vsnprintf_v2.patch from STR#3413 which documents
the previously undocumented function, so that it shows up
here in the doxygen docs:

    Files -> File List -> vsnprintf.c -> fl_vsnprintf()

This commit does not solve STR #3413, just adds the recommended documentation
for fl_vsnprintf(). Other functions in src/vsnprintf.c could use docs too.

See the bottom of comment #5 in the STR for recommendations to fully solve.

1 files changed, 33 insertions, 0 deletions

diff --git a/src/vsnprintf.c b/src/vsnprintf.c
index 08aed7fc7..606e515c1 100644
--- a/src/vsnprintf.c
+++ b/src/vsnprintf.c
@@ -25,6 +25,39 @@
 extern "C" {
 #endif
 
+/**
+  \file vsnprintf.c
+  \brief  Portable vsnprintf() implementation.
+*/
+
+/**
+  FLTK's platform independent wrapper for the vsnprintf() C library function.
+
+  This function guarantees:
+
+  - access to vsnprintf(), even on systems that don't have it (FLTK's own
+    built-in code is used)
+
+  - Guarantees NUL termination. Even if string expands larger than the buffer,
+    a terminating NUL is included, unlike some implementations of vsnprintf(),
+    notably Microsoft Visual Studio (pre-2015), which can leave the string
+    unterminated when truncated.
+
+  If the build environment for FLTK has vsnprintf(), fl_vsnprintf()
+  is just a wrapper around the compiler's provided function. Otherwise,
+  if the function is NOT available, FLTK's own built-in version is provided.
+
+  The FLTK built in provides these style options:
+
+  - %[ -+#']
+  - *  -- padding width
+  - .* -- precision width
+  - Data types: h, l, ll, L
+  - Floating point formats: E, G, e, f, g
+  - Integer formats: B, X, b, d, i, o, u, x
+  - Pointer format: p
+  - String/char: c, s, n
+*/
 int fl_vsnprintf(char* buffer, size_t bufsize, const char* format, va_list ap) {
 #if defined(HAVE_VSNPRINTF) && defined(__linux__)
   return vsnprintf(buffer, bufsize, format, ap);