Expand documentation for SetGlobalVLogLevel and SetVLogLevel.

PiperOrigin-RevId: 646031348
Change-Id: I212e34a0b89293bd9f0081047bb5a1eba5d04bcb

absl/log/globals.h

@@ -140,7 +140,7 @@ void ClearLogBacktraceLocation();
 //
 // This option tells the logging library that every logged message
 // should include the prefix (severity, date, time, PID, etc.)
-
+//
 // ShouldPrependLogPrefix()
 //
 // Returns the value of the Prepend Log Prefix option.
@@ -154,25 +154,38 @@ ABSL_MUST_USE_RESULT bool ShouldPrependLogPrefix();
 void EnableLogPrefix(bool on_off);
 
 //------------------------------------------------------------------------------
-// Set Global VLOG Level
+// `VLOG` Configuration
 //------------------------------------------------------------------------------
 //
-// Sets the global `(ABSL_)VLOG(_IS_ON)` level to `log_level`.  This level is
-// applied to any sites whose filename doesn't match any `module_pattern`.
-// Returns the prior value.
-inline int SetGlobalVLogLevel(int log_level) {
-  return absl::log_internal::UpdateGlobalVLogLevel(log_level);
+// These methods set the `(ABSL_)VLOG(_IS_ON)` threshold.  They allow
+// programmatic control of the thresholds set by the --v and --vmodule flags.
+//
+// Only `VLOG`s with a severity level LESS THAN OR EQUAL TO the threshold will
+// be evaluated.
+//
+// For example, if the threshold is 2, then:
+//
+//   VLOG(2) << "This message will be logged.";
+//   VLOG(3) << "This message will NOT be logged.";
+//
+// The default threshold is 0. Since `VLOG` levels must not be negative, a
+// negative threshold value will turn off all VLOGs.
+
+// SetGlobalVLogLevel()
+//
+// Sets the global `VLOG` level to threshold. Returns the previous global
+// threshold.
+inline int SetGlobalVLogLevel(int threshold) {
+  return absl::log_internal::UpdateGlobalVLogLevel(threshold);
 }
 
-//------------------------------------------------------------------------------
-// Set VLOG Level
-//------------------------------------------------------------------------------
+// SetVLogLevel()
 //
-// Sets `(ABSL_)VLOG(_IS_ON)` level for `module_pattern` to `log_level`.  This
-// allows programmatic control of what is normally set by the --vmodule flag.
-// Returns the level that previously applied to `module_pattern`.
-inline int SetVLogLevel(absl::string_view module_pattern, int log_level) {
-  return absl::log_internal::PrependVModule(module_pattern, log_level);
+// Sets the `VLOG` threshold for all files that match `module_pattern`,
+// overwriting any prior value. Files that don't match aren't affected.
+// Returns the threshold that previously applied to `module_pattern`.
+inline int SetVLogLevel(absl::string_view module_pattern, int threshold) {
+  return absl::log_internal::PrependVModule(module_pattern, threshold);
 }
 
 //------------------------------------------------------------------------------