summaryrefslogtreecommitdiff
path: root/absl/base/log_severity.h
diff options
context:
space:
mode:
Diffstat (limited to 'absl/base/log_severity.h')
-rw-r--r--absl/base/log_severity.h52
1 files changed, 43 insertions, 9 deletions
diff --git a/absl/base/log_severity.h b/absl/base/log_severity.h
index e247c4a9..65a3b166 100644
--- a/absl/base/log_severity.h
+++ b/absl/base/log_severity.h
@@ -24,19 +24,45 @@
namespace absl {
ABSL_NAMESPACE_BEGIN
-// Four severity levels are defined. Logging APIs should terminate the program
+// absl::LogSeverity
+//
+// Four severity levels are defined. Logging APIs should terminate the program
// when a message is logged at severity `kFatal`; the other levels have no
// special semantics.
//
-// Abseil flags may be defined with type `LogSeverity`. Dependency layering
-// constraints require that the `AbslParseFlag` overload be declared and defined
-// in the flags module rather than here. The `AbslUnparseFlag` overload is
-// defined there too for consistency.
+// Values other than the four defined levels (e.g. produced by `static_cast`)
+// are valid, but their semantics when passed to a function, macro, or flag
+// depend on the function, macro, or flag. The usual behavior is to normalize
+// such values to a defined severity level, however in some cases values other
+// than the defined levels are useful for comparison.
+//
+// Exmaple:
+//
+// // Effectively disables all logging:
+// SetMinLogLevel(static_cast<absl::LogSeverity>(100));
+//
+// Abseil flags may be defined with type `LogSeverity`. Dependency layering
+// constraints require that the `AbslParseFlag()` overload be declared and
+// defined in the flags library itself rather than here. The `AbslUnparseFlag()`
+// overload is defined there as well for consistency.
+//
+// absl::LogSeverity Flag String Representation
+//
+// An `absl::LogSeverity` has a string representation used for parsing
+// command-line flags based on the enumerator name (e.g. `kFatal`) or
+// its unprefixed name (without the `k`) in any case-insensitive form. (E.g.
+// "FATAL", "fatal" or "Fatal" are all valid.) Unparsing such flags produces an
+// unprefixed string representation in all caps (e.g. "FATAL") or an integer.
//
-// The parser accepts arbitrary integers (as if the type were `int`). It also
-// accepts each named enumerator, without regard for case, with or without the
-// leading 'k'. For example: "kInfo", "INFO", and "info" all parse to the value
-// `absl::LogSeverity::kInfo`.
+// Additionally, the parser accepts arbitrary integers (as if the type were
+// `int`).
+//
+// Examples:
+//
+// --my_log_level=kInfo
+// --my_log_level=INFO
+// --my_log_level=info
+// --my_log_level=0
//
// Unparsing a flag produces the same result as `absl::LogSeverityName()` for
// the standard levels and a base-ten integer otherwise.
@@ -47,6 +73,8 @@ enum class LogSeverity : int {
kFatal = 3,
};
+// LogSeverities()
+//
// Returns an iterable of all standard `absl::LogSeverity` values, ordered from
// least to most severe.
constexpr std::array<absl::LogSeverity, 4> LogSeverities() {
@@ -54,6 +82,8 @@ constexpr std::array<absl::LogSeverity, 4> LogSeverities() {
absl::LogSeverity::kError, absl::LogSeverity::kFatal}};
}
+// LogSeverityName()
+//
// Returns the all-caps string representation (e.g. "INFO") of the specified
// severity level if it is one of the standard levels and "UNKNOWN" otherwise.
constexpr const char* LogSeverityName(absl::LogSeverity s) {
@@ -66,6 +96,8 @@ constexpr const char* LogSeverityName(absl::LogSeverity s) {
: s == absl::LogSeverity::kFatal ? "FATAL" : "UNKNOWN";
}
+// NormalizeLogSeverity()
+//
// Values less than `kInfo` normalize to `kInfo`; values greater than `kFatal`
// normalize to `kError` (**NOT** `kFatal`).
constexpr absl::LogSeverity NormalizeLogSeverity(absl::LogSeverity s) {
@@ -77,6 +109,8 @@ constexpr absl::LogSeverity NormalizeLogSeverity(int s) {
return absl::NormalizeLogSeverity(static_cast<absl::LogSeverity>(s));
}
+// operator<<
+//
// The exact representation of a streamed `absl::LogSeverity` is deliberately
// unspecified; do not rely on it.
std::ostream& operator<<(std::ostream& os, absl::LogSeverity s);