Some improvements to Logging stdlib docs. (JuliaLang#40979)

base/logging.jl

@@ -133,9 +133,29 @@ isless(a::LogLevel, b::LogLevel) = isless(a.level, b.level)
 convert(::Type{LogLevel}, level::Integer) = LogLevel(level)
 
 const BelowMinLevel = LogLevel(-1000001)
+"""
+ Debug
+
+Alias for [`LogLevel(-1000)`](@ref LogLevel).
+"""
 const Debug = LogLevel( -1000)
+"""
+ Info
+
+Alias for [`LogLevel(0)`](@ref LogLevel).
+"""
 const Info = LogLevel( 0)
+"""
+ Warn
+
+Alias for [`LogLevel(1000)`](@ref LogLevel).
+"""
 const Warn = LogLevel( 1000)
+"""
+ Error
+
+Alias for [`LogLevel(2000)`](@ref LogLevel).
+"""
 const Error = LogLevel( 2000)
 const AboveMaxLevel = LogLevel( 1000001)
 

stdlib/Logging/docs/src/index.md

@@ -59,14 +59,14 @@ automatically extracted. Let's examine the user-defined data first:
  filtering. There are several standard levels of type [`LogLevel`](@ref);
  user-defined levels are also possible.
  Each is distinct in purpose:
- - `Debug` is information intended for the developer of the program.
- These events are disabled by default.
- - `Info` is for general information to the user.
+ - [`Logging.Debug`](@ref) (log level -1000) is information intended for the developer of
+ the program. These events are disabled by default.
+ - [`Logging.Info`](@ref) (log level 0) is for general information to the user.
  Think of it as an alternative to using `println` directly.
- - `Warn` means something is wrong and action is likely required
- but that for now the program is still working.
- - `Error` means something is wrong and it is unlikely to be recovered,
- at least by this part of the code.
+ - [`Logging.Warn`](@ref) (log level 1000) means something is wrong and action is likely
+ required but that for now the program is still working.
+ - [`Logging.Error`](@ref) (log level 2000) means something is wrong and it is unlikely to
+ be recovered, at least by this part of the code.
  Often this log-level is unneeded as throwing an exception can convey
  all the required information.
 
@@ -217,7 +217,9 @@ julia> foo()
 
 ```
 
-## Writing log events to a file
+## Examples
+
+### Example: Writing log events to a file
 
 Sometimes it can be useful to write log events to a file. Here is an example
 of how to use a task-local and global logger to write information to a text
@@ -254,6 +256,25 @@ julia> @info("a global log message")
 julia> close(io)
 ```
 
+### Example: Enable debug-level messages
+
+Here is an example of creating a [`ConsoleLogger`](@ref) that lets through any messages
+with log level higher than, or equal, to [`Logging.Debug`](@ref).
+
+```julia-repl
+julia> using Logging
+
+# Create a ConsoleLogger that prints any log messages with level >= Debug to stderr
+julia> debuglogger = ConsoleLogger(stderr, Logging.Debug)
+
+# Enable debuglogger for a task
+julia> with_logger(debuglogger) do
+ @debug "a context specific log message"
+ end
+
+# Set the global logger
+julia> global_logger(debuglogger)
+```
 
 ## Reference
 
@@ -267,6 +288,10 @@ Logging.Logging
 ```@docs
 Logging.@logmsg
 Logging.LogLevel
+Logging.Debug
+Logging.Info
+Logging.Warn
+Logging.Error
 ```
 
 ### [Processing events with AbstractLogger](@id AbstractLogger-interface)

stdlib/Logging/src/Logging.jl

@@ -12,7 +12,7 @@ module Logging
 # Doing it this way (rather than with import) makes these symbols accessible to
 # tab completion.
 for sym in [
- :LogLevel, :BelowMinLevel, :Debug, :Info, :Warn, :Error, :AboveMaxLevel,
+ :LogLevel, :BelowMinLevel, :AboveMaxLevel,
  :AbstractLogger,
  :NullLogger,
  :handle_message, :shouldlog, :min_enabled_level, :catch_exceptions,
@@ -29,6 +29,32 @@ for sym in [
  @eval const $sym = Base.CoreLogging.$sym
 end
 
+# LogLevel aliases (re-)documented here (JuliaLang/julia#40978)
+"""
+ Debug
+
+Alias for [`LogLevel(-1000)`](@ref LogLevel).
+"""
+const Debug = Base.CoreLogging.Debug
+"""
+ Info
+
+Alias for [`LogLevel(0)`](@ref LogLevel).
+"""
+const Info = Base.CoreLogging.Info
+"""
+ Warn
+
+Alias for [`LogLevel(1000)`](@ref LogLevel).
+"""
+const Warn = Base.CoreLogging.Warn
+"""
+ Error
+
+Alias for [`LogLevel(2000)`](@ref LogLevel).
+"""
+const Error = Base.CoreLogging.Error
+
 using Base.CoreLogging:
  closed_stream