Pass Severity instead of String to Logger::Formatter

[Sija]

Fixes #4355

[mverzilli]

Thanks for this @Sija (that was fast! :)). On reviewing this I noticed there's zero documentation for the Formatter. Could we add that as part of this PR? This is a breaking change so having at least basic documentation will help users fix their programs faster.

[mverzilli]

Why not just use "U" (for "Unknown")?

[Sija]

I just copy-pasted this line from previous version. Why not just severity.to_s without branching into other symbols?

[mverzilli]

Hadn't noticed it was already like that. Then let's just leave it like this.

[Sija]

@mverzilli done.

[mverzilli]

@Sija I meant to document the formatter property, which is public. What do you think about this?

1. Remove that comment from the alias definition
2. Add this on top of the formatter property:

# Customizable `Proc` (with a reasonable default)
# which the Logger uses to format and print its entries.
#
# Use this setter to provide a custom formatter.
# The Logger will invoke it with the following arguments:
#  - severity: a `Logger::Severity`.
#  - datetime: `Time`, the entry's timestamp
#  - progname: `String`, the program name, if set when the logger was built
#  - message: `String`, the body of a message
#  - io: `IO`, the Logger's stream, to which you must write the output
# you want.
#
# Example:
#
# ```
# require "logger"
#
# logger = Logger.new(STDOUT)
# logger.progname = "YodaBot"
#
# logger.formatter = Logger::Formatter.new do |severity, datetime, progname, message, io|
#   label = severity.unknown? ? "ANY" : severity.to_s
#   io << label[0] << ", [" << datetime << " #" << Process.pid << "] "
#   io << label.rjust(5) << " -- " << progname << ": " << message
# end
#
# logger.warn("Fear leads to anger. Anger leads to hate. Hate leads to suffering.")
#
# # Prints to the console:
# # "W, [2017-05-06 18:00:41 -0300 #11927]  WARN --
# #  YodaBot: Fear leads to anger. Anger leads to hate. Hate leads to suffering."
# ```

Btw, I would have liked to directly add a commit to the PR without bothering you, but I'm not sure what the best workflow for doing it is :(.

[RX14]

@mverzilli I think maintainers can push directly to most PRs now.

[Sija]

I've force-pushed the last commit with your docs added. In the future it's fine with me if you'd do it yourself. I've took a liberty to modify some interpunction and wording here & there if that's ok with you.

[Sija]

@RX14 with above option checked, they do.

[RX14]

@Sija that box is checked by default now though, so I imagine most prs don't bother to change it.

[mverzilli]

Nice, it does work :).