-
Notifications
You must be signed in to change notification settings - Fork 721
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
docs: clean up tracing_subscriber::fmt
formatter docs
#1927
Conversation
## Motivation Currently, the documentation for the `fmt` module shows examples of the output for each formatter in the top-level module. This is a lot of text that makes finding other things in the documentation more difficult. Meanwhile, the type-level docs for the various formatters are quite terse and don't offer much useful information. ## Solution This branch moves the example output to the type-level docs for the various formatters, and links to it from the list of formatters. I've also updated and expanded some of the documentation for the formatters, and added a similar list of formatters to the `fmt::format` module. Hopefully, this makes things easier to navigate? Finally, I've re-generated all example output with the latest versions of each formatter. ## Alternatives Alternatively, we could not move the example output. The initial intention for putting it in the top-level `fmt` module docs was to make it _very_ easy to find what the different formats look like. Perhaps this is worth having a lot of text to scroll through in the module-level docs?
cc @davidbarsky @lilyball I would love your opinions on the docs changes 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.
Yeah, I prefer this layout.
I agree, this new layout is better. If I want to compare formats I can just pop open the pages in tabs, which actually makes it easier to flip between the tabs to compare. It also means I can just jump directly to the format explanation by searching for the type without having to walk back up to the |
## Motivation Currently, the documentation for the `fmt` module shows examples of the output for each formatter in the top-level module. This is a lot of text that makes finding other things in the documentation more difficult. Meanwhile, the type-level docs for the various formatters are quite terse and don't offer much useful information. ## Solution This branch moves the example output to the type-level docs for the various formatters, and links to it from the list of formatters. I've also updated and expanded some of the documentation for the formatters, and added a similar list of formatters to the `fmt::format` module. Hopefully, this makes things easier to navigate? Finally, I've re-generated all example output with the latest versions of each formatter. ## Alternatives Alternatively, we could not move the example output. The initial intention for putting it in the top-level `fmt` module docs was to make it _very_ easy to find what the different formats look like. Perhaps this is worth having a lot of text to scroll through in the module-level docs?
## Motivation Currently, the documentation for the `fmt` module shows examples of the output for each formatter in the top-level module. This is a lot of text that makes finding other things in the documentation more difficult. Meanwhile, the type-level docs for the various formatters are quite terse and don't offer much useful information. ## Solution This branch moves the example output to the type-level docs for the various formatters, and links to it from the list of formatters. I've also updated and expanded some of the documentation for the formatters, and added a similar list of formatters to the `fmt::format` module. Hopefully, this makes things easier to navigate? Finally, I've re-generated all example output with the latest versions of each formatter. ## Alternatives Alternatively, we could not move the example output. The initial intention for putting it in the top-level `fmt` module docs was to make it _very_ easy to find what the different formats look like. Perhaps this is worth having a lot of text to scroll through in the module-level docs?
# 0.3.9 (Feb 17, 2022) This release updates the minimum supported Rust version (MSRV) to 1.49.0, and updates the (optional) dependency on `parking_lot` to v0.12. ### Changed - Updated minimum supported Rust version (MSRV) to 1.49.0 ([#1913]) - `parking_lot`: updated to v0.12 ([008339d]) ### Added - **fmt**: Documentation improvements ([#1926], [#1927]) [#1913]: #1913 [#1926]: #1926 [#1927]: #1927 [008339d]: 008339d
# 0.3.9 (Feb 17, 2022) This release updates the minimum supported Rust version (MSRV) to 1.49.0, and updates the (optional) dependency on `parking_lot` to v0.12. ### Changed - Updated minimum supported Rust version (MSRV) to 1.49.0 ([#1913]) - `parking_lot`: updated to v0.12 ([008339d]) ### Added - **fmt**: Documentation improvements ([#1926], [#1927]) [#1913]: #1913 [#1926]: #1926 [#1927]: #1927 [008339d]: 008339d
# 0.3.9 (Feb 17, 2022) This release updates the minimum supported Rust version (MSRV) to 1.49.0, and updates the (optional) dependency on `parking_lot` to v0.12. ### Changed - Updated minimum supported Rust version (MSRV) to 1.49.0 ([tokio-rs#1913]) - `parking_lot`: updated to v0.12 ([008339d]) ### Added - **fmt**: Documentation improvements ([tokio-rs#1926], [tokio-rs#1927]) [tokio-rs#1913]: tokio-rs#1913 [tokio-rs#1926]: tokio-rs#1926 [tokio-rs#1927]: tokio-rs#1927 [008339d]: tokio-rs@008339d
Motivation
Currently, the documentation for the
fmt
module shows examples of theoutput for each formatter in the top-level module. This is a lot of text
that makes finding other things in the documentation more difficult.
Meanwhile, the type-level docs for the various formatters are quite
terse and don't offer much useful information.
Solution
This branch moves the example output to the type-level docs for the
various formatters, and links to it from the list of formatters. I've
also updated and expanded some of the documentation for the formatters,
and added a similar list of formatters to the
fmt::format
module.Hopefully, this makes things easier to navigate?
Finally, I've re-generated all example output with the latest versions
of each formatter.
Alternatives
Alternatively, we could not move the example output. The initial
intention for putting it in the top-level
fmt
module docs was to makeit very easy to find what the different formats look like. Perhaps
this is worth having a lot of text to scroll through in the
module-level docs?