cgraph: Doxygen-ize and further explain 'PRISIZE_T'

diff --git a/lib/cgraph/prisize_t.h b/lib/cgraph/prisize_t.h
index a19c8ef13ce7133579a2deb84fbbae0be03af969..8cf4b25bc254d9218d92ac3c94fd817ad499ee06 100644 (file)
--- a/lib/cgraph/prisize_t.h
+++ b/lib/cgraph/prisize_t.h
@@ -1,6 +1,19 @@
 #pragma once
 
-// `PRIu64`-alike for printing size_t
+/// \brief \p PRIu64 alike for printing \p size_t
+///
+/// Use this as:
+///
+/// \code{.c}
+///   size_t value = 42;
+///   printf("value is %" PRISIZE_T ".", value);
+///   // prints “value is 42.”
+/// \endcode
+///
+/// Note that leaving a space on either side of \p PRISIZE_T does not seem
+/// relevant in C, but if you omit this in C++ it will be interpreted as a
+/// user-defined string literal indicator. So it is best to always use a space
+/// on either side.
 #ifdef __MINGW64__
   // Microsoft’s Visual C Runtime (msvcrt) ships a printf that does not
   // understand "%zu". MSVC itself uses a different printf that does not rely on