ruby-changes:71826
From: Burdette <ko1@a...>
Date: Sat, 14 May 2022 05:02:28 +0900 (JST)
Subject: [ruby-changes:71826] 9639dc91d9 (master): [ruby/logger] [DOC] Enhanced RDoc for Logger (https://github.com/ruby/logger/pull/77)
https://git.ruby-lang.org/ruby.git/commit/?id=9639dc91d9 From 9639dc91d936a637db56c19664a46c024059bc40 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 13 May 2022 15:02:05 -0500 Subject: [ruby/logger] [DOC] Enhanced RDoc for Logger (https://github.com/ruby/logger/pull/77) Enhanced RDoc for Logger https://github.com/ruby/logger/commit/c601ed0370 Co-authored-by: Peter Zhu <peter@p...> --- lib/logger.rb | 469 ++++++++++++++++++++++++++++++---------------------------- 1 file changed, 240 insertions(+), 229 deletions(-) diff --git a/lib/logger.rb b/lib/logger.rb index 62ab20dc2e..cbb0da676b 100644 --- a/lib/logger.rb +++ b/lib/logger.rb @@ -38,10 +38,12 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L38 # # # Single log file. # logger = Logger.new('t.log') -# # Size-based rotated log: 3 10-megabyte files. +# # Size-based rotated logging: 3 10-megabyte files. # logger = Logger.new('t.log', 3, 10485760) -# # Period-based rotated log: daily (also allowed: 'weekly', 'monthly'). +# # Period-based rotated logging: daily (also allowed: 'weekly', 'monthly'). # logger = Logger.new('t.log', 'daily') +# # Log to an IO stream. +# logger = Logger.new($stdout) # # Add entries (level, message) with Logger#add: # @@ -52,7 +54,22 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L54 # logger.add(Logger::FATAL, 'Fatal error') # logger.add(Logger::UNKNOWN, 'Most severe') # -# There are also these shorthand methods: +# Close the log with Logger#close: +# +# logger.close +# +# == Entries +# +# You can add entries with method Logger#add: +# +# logger.add(Logger::DEBUG, 'Maximal debugging info') +# logger.add(Logger::INFO, 'Non-error information') +# logger.add(Logger::WARN, 'Non-error warning') +# logger.add(Logger::ERROR, 'Non-fatal error') +# logger.add(Logger::FATAL, 'Fatal error') +# logger.add(Logger::UNKNOWN, 'Most severe') +# +# These shorthand methods also add entries: # # logger.debug('Maximal debugging info') # logger.info('Non-error information') @@ -61,36 +78,9 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L78 # logger.fatal('Fatal error') # logger.unknown('Most severe') # -# For each method in the two groups immediately above, -# you can omit the string message and provide a block instead. -# Doing so can have two benefits: -# -# - Context: the block can evaluate the entire program context -# and create a context-dependent message. -# - Performance: the block is not evaluated unless the log level -# permits the entry actually to be written: -# -# logger.error { my_slow_message_generator } -# -# Contrast this with the string form, where the string is -# always evaluated, regardless of the log level: -# -# logger.error("#{my_slow_message_generator}") -# -# Close the log with Logger#close: -# -# logger.close -# -# == Log Stream -# -# When you create a \Logger instance, you specify an IO stream -# for the logger's output, usually either an open File object -# or an IO object such as <tt>$stdout</tt> or <tt>$stderr</tt>. -# -# == Entries -# -# When you call instance method #add (or its alias #log), -# an entry may (or may not) be written to the log; +# When you call any of these methods, +# the entry may or may not be written to the log, +# depending on the entry's severity and on the log level; # see {Log Level}[rdoc-ref:Logger@Log+Level] # # An entry always has: @@ -106,8 +96,8 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L96 # Example: # # logger = Logger.new($stdout) -# logger.add(Logger::INFO, 'msg', 'progname') -# # => I, [2022-05-07T17:21:46.536234 #20536] INFO -- progname: msg +# logger.add(Logger::INFO, 'My message.', 'mung') +# # => I, [2022-05-07T17:21:46.536234 #20536] INFO -- mung: My message. # # The default format for an entry is: # @@ -124,15 +114,27 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L114 # # You can use a different entry format by: # -# - Calling #add with a block (affects only the one entry). -# - Setting a format proc with method -# {formatter=}[Logger.html#attribute-i-formatter] -# (affects following entries). +# - Setting a custom format proc (affects following entries); +# see {formatter=}[Logger.html#attribute-i-formatter]. +# - Calling any of the methods above with a block +# (affects only the one entry). +# Doing so can have two benefits: +# +# - Context: the block can evaluate the entire program context +# and create a context-dependent message. +# - Performance: the block is not evaluated unless the log level +# permits the entry actually to be written: +# +# logger.error { my_slow_message_generator } +# +# Contrast this with the string form, where the string is +# always evaluated, regardless of the log level: +# +# logger.error("#{my_slow_message_generator}") # # === \Severity # -# The severity of a log entry, which is specified in the call to #add, -# does two things: +# The severity of a log entry has two effects: # # - Determines whether the entry is selected for inclusion in the log; # see {Log Level}[rdoc-ref:Logger@Log+Level]. @@ -142,7 +144,7 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L144 # === Timestamp # # The timestamp for a log entry is generated automatically -# when the entry is created (by a call to #add). +# when the entry is created. # # The logged timestamp is formatted by method # {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime] @@ -160,33 +162,30 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L162 # # === Message # -# The message is an optional argument to method #add: +# The message is an optional argument to an entry method: # # logger = Logger.new($stdout) # logger.add(Logger::INFO, 'My message') # # => I, [2022-05-07T18:15:37.647581 #20536] INFO -- : My message # -# The message object may be a string, or an object that can be converted -# to a string. +# For the default entry formatter, <tt>Logger::Formatter</tt>, +# the message object may be: # -# *Note*: \Logger does not escape or sanitize any messages passed to it. +# - A string: used as-is. +# - An Exception: <tt>message.message</tt> is used. +# - Anything else: <tt>message.inspect</tt> is used. +# +# *Note*: Logger::Formatter does not escape or sanitize +# the message passed to it. # Developers should be aware that malicious data (user input) -# may be passed to \Logger, and should explicitly escape untrusted data. +# may be in the message, and should explicitly escape untrusted data. # # You can use a custom formatter to escape message data; -# this formatter uses -# {String#dump}[https://docs.ruby-lang.org/en/master/String.html#method-i-dump] -# to escape the message string: -# -# original_formatter = logger.formatter || Logger::Formatter.new -# logger.formatter = proc { |sev, time, progname, msg| -# original_formatter.call(sev, time, progname, msg.dump) -# } -# logger.info(input) +# see the example at {formatter=}[Logger.html#attribute-i-formatter]. # # === Program Name # -# The program name is an optional argument to method #add: +# The program name is an optional argument to an entry method: # # logger = Logger.new($stdout) # logger.add(Logger::INFO, 'My message', 'mung') @@ -205,6 +204,8 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L204 # The current program name may be retrieved with method # {progname}[Logger.html#attribute-i-progname]: # +# logger.progname # => "mung" +# # == Log Level # # The log level setting determines whether an entry is actually @@ -255,7 +256,7 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L256 # # logger.level = Logger::ERROR # -# There are also these shorthand methods for setting the level: +# These shorthand methods also set the level: # # logger.debug! # => 0 # logger.info! # => 1 @@ -266,13 +267,13 @@ require_relative 'logger/errors' https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L267 # You can retrieve the log level with method # {level}[Logger.html#attribute-i-level]: # -# logger.level = 3 +# logger.level = Logger::ERROR # logger.level # => 3 # -# There are also these methods for determining whether a given +# These methods return whether a given # level is to be written: # -# logger.level = 3 +# logger.level = Logger::ERROR # logger.debug? # => false # logger.info? # => false # logger.warn? # => false @@ -381,9 +382,18 @@ class Logger https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L382 # Logging severity threshold (e.g. <tt>Logger::INFO</tt>). attr_reader :level - # Set logging severity threshold. + # Sets the log level; returns +severity+. + # See {Log Level}[rdoc-ref:Logger@Log+Level]. + # + # Argument +severity+ may be an integer, a string, or a symbol: + # + # logger.level = Logger::ERROR # => 3 + # logger.level = 3 # => 3 + # logger.level = 'error' # => "error" + # logger.level = :error # => :error + # + # Logger#sev_threshold= is an alias for Logger#level=. # - # +severity+:: The Severity of the log message. def level=(severity) if severity.is_a?(Integer) @level = severity @@ -410,74 +420,117 @@ class Logger https://github.com/ruby/ruby/blob/trunk/lib/logger.rb#L420 # Program name to include in log messages. attr_accessor :progname - # Set date-time format. + # Sets the date-time format. + # + # Argument +datetime_format+ should be either of these: + # + # - A string suitable for use as a format for method + # {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime]. + # - +nil+: (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/