std::fmt: reorder docs #65332
Merged
std::fmt: reorder docs #65332
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
r? @cramertj (rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
RalfJung
commented
Oct 12, 2019
| //! | ||
| //! # Syntax | ||
| //! | ||
| //! To summarize, you can find the full grammar of format strings. |
There was a problem hiding this comment.
This line is the only new text I wrote; everything else is just moved around.
RalfJung
commented
Oct 12, 2019
src/liballoc/fmt.rs
Outdated
| @@ -97,7 +97,187 @@ | |||
| //! actual object being formatted, and the number of characters must have the | |||
| //! type [`usize`]. | |||
There was a problem hiding this comment.
The section ending here ("Argument types") still sticks out to me. I basically cannot parse it, and I have no idea what it is trying to tell me.
The first sentence, "Each argument's type is dictated by the format string" is not even correct, is it? {} does not determine the type of the argument at all. Also this uses the .* syntax, which is really subtle in how it consumes two format arguments. That is explained way later though, in the subsection dedicated entirely to specifying the precision.
My personal feeling is that this subsection here does not add anything useful and is confusing. Hence I propose removing it.
There was a problem hiding this comment.
I agree. It could be left out here completely, and the bit about precision having to be usize is mentioned below already.
RalfJung
commented
Oct 12, 2019
| //! Each argument's type is dictated by the format string. | ||
| //! There are various parameters which require a particular type, however. | ||
| //! An example is the `{:.*}` syntax, which sets the number of decimal places | ||
| //! in floating-point types: |
There was a problem hiding this comment.
Okay, I now amended this to also remove the following confusing subsection:
-//! ## Argument types
-//!
-//! Each argument's type is dictated by the format string.
-//! There are various parameters which require a particular type, however.
-//! An example is the `{:.*}` syntax, which sets the number of decimal places
-//! in floating-point types:
-//!
-//! ```
-//! let formatted_number = format!("{:.*}", 2, 1.234567);
-//!
-//! assert_eq!("1.23", formatted_number)
-//! ```
-//!
-//! If this syntax is used, then the number of characters to print precedes the
-//! actual object being formatted, and the number of characters must have the
-//! type [`usize`].
|
@bors r+ rollup |
|
📌 Commit 504cc20 has been approved by |
bors
added
S-waiting-on-bors
tmandry
added a commit
to tmandry/rust
that referenced
this pull request
Oct 15, 2019
std::fmt: reorder docs This moves the "Formatting Parameters" section up above right after the discussion of named and positional arguments. Then comes the "Syntax" section, summarizing the discussion of format string syntax. And only *then* we get to "Formatting Traits" -- that section has some *huge* code examples, so it really should not interrupt the discussion of the grammar. Also users are much more likely to come here to learn about the format string grammar than to come here to learn about the `Binary` trait.
bors
added a commit
that referenced
this pull request
Oct 15, 2019
Rollup of 10 pull requests Successful merges: - #65170 (rustc_metadata: Privatize private code and remove dead code) - #65260 (Optimize `LexicalResolve::expansion`.) - #65261 (Remove `Option` from `TokenStream`) - #65332 (std::fmt: reorder docs) - #65340 (Several changes to the codegen backend organization) - #65365 (Include const generic arguments in metadata) - #65398 (Bring attention to suggestions when the only difference is capitalization) - #65410 (syntax: add parser recovery for intersection- / and-patterns `p1 @ p2`) - #65415 (Remove an outdated test output file) - #65416 (Minor sync changes) Failed merges: r? @ghost
|
☔ The latest upstream changes (presumably #65422) made this pull request unmergeable. Please resolve the merge conflicts. |
bors
added
S-waiting-on-author
Centril
added a commit
to Centril/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
tmandry
added a commit
to tmandry/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
tmandry
added a commit
to tmandry/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
Centril
added a commit
to Centril/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
tmandry
added a commit
to tmandry/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
tmandry
added a commit
to tmandry/rust
that referenced
this pull request
Oct 18, 2019
reorder fmt docs for more clarity I adjusted these docs in rust-lang#65332 but wasn't happy with the result when seeing it in rustdoc. So this reorders the subsections in the "Formatting Parameters" section to be more logical (subsections that reference `width` come after the `width` subsection) and they also all have examples now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This moves the "Formatting Parameters" section up above right after the discussion of named and positional arguments. Then comes the "Syntax" section, summarizing the discussion of format string syntax.
And only then we get to "Formatting Traits" -- that section has some huge code examples, so it really should not interrupt the discussion of the grammar. Also users are much more likely to come here to learn about the format string grammar than to come here to learn about the
Binarytrait.