New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add unit tests, docs related to available log level names #189
add unit tests, docs related to available log level names #189
Conversation
Heads-up: The failed CI check is unrelated to this PR. The "Check formatting" check is complaining about a trailing comma on an existing line of code, not something introduced here. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the PR, I like the improved docs!
I've now fixed the rustfmt issue on the master branch, could you rebase? Also, why do your commit messages all start with [N of 9]:
? I've seen this before but don't really understand what value it provides.
src/lib.rs
Outdated
@@ -123,19 +123,30 @@ | |||
//! The letter case is not significant for the logging level names; e.g., | |||
//! `debug`, `DEBUG`, and `dEbuG` all represent the same logging level. | |||
//! | |||
//! There is also a pseudo logging level, `OFF`, which may be specified to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since the "canonical" (most often referred to) form is lowercase, maybe this should be lowercase as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay. I have only limited experience with env_logger
; my experience with other loggers in other language ecosystems has conditioned me to recognize the upper case as something akin to either a global constant or the name of a global variable name. But I'm not fixated on it :-)
As I'm tweaking things for my rebase, I'll try to work in a mention that lowercase is preferred.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I wasn't saying that it should be preferred. Just that the docs most often use the lowercase form. I was suggesting
//! There is also a pseudo logging level, `OFF`, which may be specified to | |
//! There is also a pseudo logging level, `off`, which may be specified to |
src/lib.rs
Outdated
//! * `info` turns on all info logging | ||
//! * `INFO` turns on all info logging (same as previous) | ||
//! * `hello=debug` turns on debug logging for 'hello' | ||
//! * `hello=DEBUG` turns on debug logging for 'hello' (same as previous) | ||
//! * `hello,std::option` turns on hello, and std's option logging | ||
//! * `error,hello=warn` turn on global error logging and also warn for hello | ||
//! * `error,hello=off`` turn on global error logging, but turn off logging for hello | ||
//! * `OFF` turns off all logging for the application |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And here.
For this one I was deliberately trying to show that both upper and lower case variants are accepted. It's one thing to state the rules in the prose, but I think that seeing examples of both will help more people to recognize both as valid "on sight". But maybe there's a better way to convey that; I've got a couple of ideas to try. More on that shortly...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right. Could also keep this one as-is.
@jplatte Thanks for the review!
Sure; I'll do that as soon as I make the adjustments outlined below.
It's mainly a way of organizing work informed by experience reviewing patch series in email threads. It attaches to a commit useful metadata that will live with the commit indefinitely (unless it gets removed in a future rebase or "squash and merge"). Having that small bit of metadata handy avoids the need to re-derive it, and provides a number of small benefits that can make things easier to manage, especially when working with a large number of projects and branches within those projects.
|
@jplatte By the way, thanks for fixing the |
I only re-ran
I was not expecting such an elaborate reply! Doing a lot of rebases myself I don't really get the benefits for that, but I can see how it would be nice to see when reviewing large change sets as a quick gauge for how far into the review one is. I'll be doing the default GitHub "merge", i.e. with a merge commit, if that matters. |
These test parse_spec() against strings that contain only a legit log level name. Several case variants are exercised, and confirmed to obtain the same result.
Add tests that elaborate on the existing parse_default() unit test. These new tests exercise all of log::Level variants (plus the "OFF" pseudo log level), and also serve as minimal examples of how to set the default log level. For example, they exercise both lowercase and uppercase variants. There is one mixed case variant test thrown in, too, since that is specifically allowed for by the external log::Level::from_str() implementation on which we depend. There is also a test to ensure all log::Level variants are accounted for in the above tests. That one is intended to avoid the false sense of comfort from passing tests in the unlikely event that a new variant is added to the externally defined log::Level enum. (Note that this compile-time check does not include the "OFF" pseudo log level, as it exists outside of the log::Level enum.)
The fact that user-specified logging level names are handled in a case-insensitive fashion is now noted in both the 'README.md' file and in the crate-level API docs.
The first mention of the 'RUST_LOG' environment variable in the prose in both the 'README.md' file and in the crate-level API docs now uses bold text markdown. This is intended to draw attention to it for both first time readers and for those skimming the docs quickly.
For symmetry with the 'README.md' file, the crate-level API docs now note that 'env_logger' can be configured by means other than via environment variables, and (like README.md) directs the user to the examples in the GitHub repo. This is useful information for somebody first discovering the 'env_logger' crate on crates.io; it provides a more comprehensive picture of how the crate is intended to be used.
The "Enabling logging" section of the crate-level docs are here updated to clarify the default behavior as it pertains to the logging level. Previously, the first paragraph stated that all logging is disabled except for the default level, but the third paragraph stated that if no log level was specified then /all/ logging was enabled. It turns out that the third paragraph was really intended as a continuation of the second paragraph, the applicable context of which is limited to those scenarios in which a logging directive has been supplied. This changeset reworks the paragraph structure slightly to make the intent more clear, and also to make it easy to quickly identify the most important aspects: A. Old para 1 split into two separate paras: - first states clearly the default behavior (now in bold) - second introduces 'RUST_LOG' and logging directives B. Old para 3 split into two separate paras: - first now qualifies the statement with "When specifying the crate name or a module path..." - second introduces log level names C. The existing statement that describes the behavior when only a log level is provided (it sets the global log level) is now in bold markdown. It might make sense to refine this further at some point so that the flow of the text answers in order the user's questions: 1. "What is the default behavior?" (Already first; good.) 2. "How do I set the log level for the entire app?" 3. "How do I set the log level more surgically?" Our current flow is: (1), (3), (2)
The 'README.md' and crate-level API docs are both updated to show the available logging levels in a bulleted list (rather then a comma-separated list in the prose), and to note that they correspond to the externally defined log::Level enum in the 'log' crate. For the README.md file, this is an addition. The universe of valid log levels was not previously listed there. The order of the log levels is also now sorted in the list highest precedence to lowest: error, warn, info, debug, trace The previous order in which they were presented was: debug, error, info, warn, trace
Add markdown to emphasize (typical rendering would be italics) the term "logging directive" upon the first mention in the text.
Since our convention throughout the docs is to use the lower case form of log level names (e.g., "info" rather than "INFO"), users might mistakenly infer that we are implying that only the lower case forms are legit. Careful readers might even suspect that the handful of departures are typos rather than deliberate examples. This change adds a blurblet to the README.md and to the top-level API docs explaining the convention and the motivation for using it (consistency).
f81a239
to
5595a4d
Compare
Yeah, I kinda got on roll there... :-)
I generally prefer that , too, because it keeps a more perfect record of the already-massaged history. I just pushed my rebased update. It's identical to the previous set with two exceptions:
Please take a look when you can. I'm happy to refine it further, too. |
This PR adds some unit tests and freshens up docs related to logging levels.
This work started as an effort to provide unit tests that exercise simple scenarios in which a single logging level is specified for the entire application (without any more specific logging directives). It grew into a bit of a doc updating effort, too.
The unifying theme behind the individual commits in this series is the surfacing of simple facts about the
env_logger
crate. These changes help provide answers to some fairly basic questions such as:INFO
allowed in addition toinfo
?"The doc changes also include fixes to some contradictory statements about what the default behavior is.
Most of this is just gathering data from elsewhere else and putting it where people are already looking (info from the README.md file that wasn't in the crate-level API docs (or vice versa); info that can be guessed at from glancing at the
log
crate's API docs, but which are important for usingenv_logger
with confidence; and so on). The idea is that the user reading the crate-level API docs on crates.io should get roughly the same sense for the crate as does the person reading the project's 'README.md' file on GitHub.The newly added unit tests exercise functionality in a way that is more basic than the existing tests (that involve more sophisticated logging directives). These new tests also serve as easy to locate in-tree examples of simple use.
All in all, these changes help make the documentation of
env_logger
more self contained -- able to stand better on its own, and with less reliance on the user's familiarity with thelog
crate.