8064779: Add additional comments for "8062370: Various minor code improvements"

Provide additional comments to jio_snprintf and jio_vsnprintf

Reviewed-by: simonis, coleenp, mgronlun

hotspot/src/share/vm/prims/jvm.cpp

@@ -2593,6 +2593,10 @@ int jio_vsnprintf(char *str, size_t count, const char *fmt, va_list args) {
   if ((intptr_t)count <= 0) return -1;
 
   int result = vsnprintf(str, count, fmt, args);
+  // Note: on truncation vsnprintf(3) on Unix returns numbers of
+  // characters which would have been written had the buffer been large
+  // enough; on Windows, it returns -1. We handle both cases here and
+  // always return -1, and perform null termination.
   if ((result > 0 && (size_t)result >= count) || result == -1) {
     str[count - 1] = '\0';
     result = -1;

hotspot/src/share/vm/prims/jvm.h

@@ -1167,10 +1167,14 @@ JVM_NativePath(char *);
  * be renamed to JVM_* in the future?
  */
 
-/*
+/* jio_snprintf() and jio_vsnprintf() behave like snprintf(3) and vsnprintf(3),
- * BE CAREFUL! The following functions do not implement the
+ *  respectively, with the following differences:
- * full feature set of standard C printf formats.
+ * - The string written to str is always zero-terminated, also in case of
- */
+ *   truncation (count is too small to hold the result string), unless count
+ *   is 0. In case of truncation count-1 characters are written and '\0'
+ *   appendend.
+ * - If count is too small to hold the whole string, -1 is returned across
+ *   all platforms. */
 JNIEXPORT int
 jio_vsnprintf(char *str, size_t count, const char *fmt, va_list args);