Skip to content
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

Merged
merged 2 commits into from Feb 17, 2022

Conversation

hawkw
Copy link
Member

@hawkw hawkw commented Feb 15, 2022

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?
@hawkw hawkw requested review from davidbarsky and a team as code owners February 15, 2022 19:51
@hawkw
Copy link
Member Author

hawkw commented Feb 15, 2022

cc @davidbarsky @lilyball I would love your opinions on the docs changes here!

Copy link
Member

@davidbarsky davidbarsky left a 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.

@lilyball
Copy link
Contributor

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 tracing_subscriber::fmt module to find them.

@hawkw hawkw enabled auto-merge (squash) February 17, 2022 19:03
@hawkw hawkw disabled auto-merge February 17, 2022 19:46
@hawkw hawkw merged commit 2ceb32f into master Feb 17, 2022
@hawkw hawkw deleted the eliza/move-formatter-examples branch February 17, 2022 19:46
hawkw added a commit that referenced this pull request Feb 17, 2022
## 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?
hawkw added a commit that referenced this pull request Feb 17, 2022
## 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?
hawkw added a commit that referenced this pull request Feb 17, 2022
# 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
hawkw added a commit that referenced this pull request Feb 18, 2022
# 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants