Document panic and format edition/verions, and improve xrefs #96518

ijackson · 2022-04-28T13:45:21Z

This MR addresses three somewhat-related issues:

The primary stdlib docs for panic! did not document the 2021 edition differences.
The primary docs forformat! (in std::fmt) did not document the version requirement for implicit capture.
The primary docs for format! (in std::fmt) were badly referenced. Somehow every time I wanted them I ended up in format_args! or somewhere, clicking round in circles...

Having a section for this inspired by the docs for array::IntoIterator

For most things in the stdlib, there's the rustdoc-generated version annotations. I don't think we can do this here, so just write prose. I have tried to be as terse as possible while still noting the relevant gotchas.

That xref contains the actual documentation for what format! does. It should be very prominent - particularly, more so than the other links.

rust-highfive · 2022-04-28T13:45:24Z

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with r? rust-lang/libs-api @rustbot label +T-libs-api -T-libs to request review from a libs-api team reviewer. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

Stabilizing library features
Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
Changing public documentation in ways that create new stability guarantees
Changing observable runtime behavior of library APIs

rust-highfive · 2022-04-28T13:45:25Z

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

scottmcm

Thanks for sending the PR! I like the approach of sending things consistently to the module documentation, rather than to the various macros.

Please address the various comments -- either with changes or with prose saying why you disagree -- then mark the PR as ready for review again with @rustbot ready.

scottmcm · 2022-05-13T07:27:11Z

library/alloc/src/fmt.rs

@@ -84,6 +84,7 @@
 //!
 //! If a named parameter does not appear in the argument list, `format!` will
 //! reference a variable with that name in the current scope.
+//! (Rust 1.58 and later; in [`panic!`], requires Rust 2021.)


Please remove this line. We don't include version numbers in the docs for every difference -- we host versioned copies of the docs (like https://doc.rust-lang.org/1.57.0/std/macro.format.html) so people using a particular version can see what that version supports. And we don't need to document panic!'s edition behaviour here -- that's fine just in its own documentation.

Suggested change

//! (Rust 1.58 and later; in [`panic!`], requires Rust 2021.)

scottmcm · 2022-05-13T07:35:51Z

library/core/src/macros/panic.md

@@ -64,6 +64,25 @@ For more detailed information about error handling check out the [book] or the
 If the main thread panics it will terminate all your threads and end your
 program with code `101`.

+# Editions


Thanks, having this written out here is really handy 👍

One request: Can you put the information about the newest edition first in this section? We want to optimize the docs for people using the latest edition, and have people still using older ones need to scan down to find their behaviour, rather than having people using 2021 need to hunt.

Maybe it could work well to make subsections here? Sketch,

# Editions ## 2021 and later ... `panic!` always uses formatting; use `panic_any` if you want a value ... ## 2018 and 2015 ... panics with a payload of literally ...

scottmcm · 2022-05-13T07:37:25Z

library/core/src/macros/panic.md

@@ -9,7 +9,7 @@ tests. `panic!` is closely tied with the `unwrap` method of both
 `panic!` when they are set to [`None`] or [`Err`] variants.

 When using `panic!()` you can specify a string payload, that is built using
-the [`format!`] syntax. That payload is used when injecting the panic into
+the [`format!` syntax]. That payload is used when injecting the panic into


suggestion: maybe just say

Suggested change

the [`format!` syntax]. That payload is used when injecting the panic into

the [formatting syntax]. That payload is used when injecting the panic into

rather that mentioning a particular macro? That avoids a conversation about whether it's "the format! syntax" or "the format_args! syntax" or ...

JohnCSimon · 2022-06-18T22:58:26Z

ping from triage:
@ijackson - can you address the build failures and comments from the reviewer? thank you

JohnCSimon · 2022-07-23T23:55:10Z

@ijackson
Ping from triage: I'm closing this due to inactivity, Please reopen when you are ready to continue with this.
Note: if you do please open the PR BEFORE you push to it, else you won't be able to reopen - this is a quirk of github.
Thanks for your contribution.

@rustbot label: +S-inactive

Document panic behavior across editions, and improve xrefs This revives (parts of) rust-lang#96518. r? `@scottmcm` Cc `@ijackson`

ijackson added 6 commits April 28, 2022 14:40

panic macro: Document edition differences

c513b0d

Having a section for this inspired by the docs for array::IntoIterator

Document fmt implicit args required Rust version.

562c89c

For most things in the stdlib, there's the rustdoc-generated version annotations. I don't think we can do this here, so just write prose. I have tried to be as terse as possible while still noting the relevant gotchas.

panic macro: Link directly to format syntax, not to format!

1720711

print macros: add xrefs to format syntax documentation

243f177

format macro: Make xref to std::fmt much more prominent

58b0ab5

That xref contains the actual documentation for what format! does. It should be very prominent - particularly, more so than the other links.

format_args: Make xref to format argument syntax much more prominent

bd0f059

rust-highfive assigned scottmcm Apr 28, 2022

rustbot added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Apr 28, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Apr 28, 2022

This comment has been minimized.

Sign in to view

Fix trailing whitespace

8be3d46

scottmcm requested changes May 13, 2022

View reviewed changes

scottmcm added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 13, 2022

JohnCSimon closed this Jul 23, 2022

rustbot added the S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs. label Jul 23, 2022

RalfJung mentioned this pull request Aug 28, 2023

Document panic behavior across editions, and improve xrefs #115310

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document panic and format edition/verions, and improve xrefs #96518

Document panic and format edition/verions, and improve xrefs #96518

ijackson commented Apr 28, 2022

rust-highfive commented Apr 28, 2022

rust-highfive commented Apr 28, 2022

This comment has been minimized.

scottmcm left a comment

scottmcm May 13, 2022

scottmcm May 13, 2022

scottmcm May 13, 2022

JohnCSimon commented Jun 18, 2022

JohnCSimon commented Jul 23, 2022

	the [`format!` syntax]. That payload is used when injecting the panic into
	the [formatting syntax]. That payload is used when injecting the panic into

Document panic and format edition/verions, and improve xrefs #96518

Document panic and format edition/verions, and improve xrefs #96518

Conversation

ijackson commented Apr 28, 2022

rust-highfive commented Apr 28, 2022

rust-highfive commented Apr 28, 2022

This comment has been minimized.

scottmcm left a comment

Choose a reason for hiding this comment

scottmcm May 13, 2022

Choose a reason for hiding this comment

scottmcm May 13, 2022

Choose a reason for hiding this comment

scottmcm May 13, 2022

Choose a reason for hiding this comment

JohnCSimon commented Jun 18, 2022

JohnCSimon commented Jul 23, 2022