Beautify pin! docs #108973

est31 · 2023-03-10T09:35:28Z

This makes pin docs a little bit less jargon-y and easier to read, by

splitting up the sentences
making them less interrupted by punctuation
turning the footnotes into paragraphs, as they contain useful information that shouldn't be hidden in footnotes. Footnotes also interrupt the read flow.

rustbot · 2023-03-10T09:35:34Z

(rustbot has picked a reviewer for you, use r? to override)

rustbot · 2023-03-10T09:35:37Z

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 @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. 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

T-Dark0 · 2023-03-11T22:27:27Z

library/core/src/pin.rs

+/// the body of a non-`async` function), in `async` contexts or in the body of a
+/// generator this isn't neccessarily the case. Here, any locals crossing an
+/// `.await`/yield point are part of the state captured by the
+/// `Future`/Generator, and will use the storage of those, which typically means


which typically means heap storage

I feel this is a bit misleading. It means heap storage only if the future/generator where this macro is invoked is moved to the heap. This is admittedly often the case, but I fear the current phrasing might cause people to believe this macro performs boxing in and of itself.

Perhaps it could be modified to

Which, if the future/generator is boxed, means heap storage

Often times it's completely hidden from the user what is happening. You just await up until the top where you have #[tokio::main] or whatever. Internally it might use heap storage, but it's hidden from the user. So I'm not sure if "if the future/generator is boxed" is going to help much. I added the sentence to make it clear that non-stack options exist so "locally" doesn't automatically imply stack.

Honestly, I think we should go all the way and actively avoid a reference to "stack-pinning" here if we can, as it has a "Don't think about the pink elephant" quality to it. Instead, it might be best to express that "local" is relative to whatever is actually being pinned, thus it uses the same storage (and implies the same lifetime). If a programmer is coming to this from JS or Python, their notion of these ideas is much more abstract and discussing "stack" and "heap" is somewhat of a distraction in this case.

I think for programmers coming from high level languages it's useful to explain the distinction to them, because it's a great opportunity for them to learn about it. If we hide this detail from them then where else would they find out about it? It shouldn't be some secret that people "in the know" know. It might seem obvious to you and me, but just a few days ago I found these two paragraphs to contain very interesting information, at least after I managed to parse them :).

I don't think that a "don't think of the pink elephant" situation applies here, because it's not wrong to think about it as stack storage. On a high level it looks like stack storage, as that's the point of async fn and blocks. It's only on a lower level where the stack analogy is wrong. And it's just as wrong for any other local that lives past an await boundary, it's just that, correct me if I'm wrong, one of the big use cases of Pin is such situations.

I am speaking of myself when I discuss people who started as JavaScript programmers (a relatively new one to boot) and went into Rust and found the existing documentation on things like heap and stack strewn about the stdlib docs frustrating and confusing: I think it is familiarity bias that suggests that terms like the "stack" and "heap" are lightweight and easy to teach, such that it can be easily shimmed inside documents about something else. They're jargon.

What a Rust programmer is really concerned about (will be forced to care about!) is the lifetime. And as a JavaScript programmer, the idea that a "stack frame" existed and that it bounded the lifetime of something on the stack was not a simple thing to get across. I think I didn't learn that until after... a year of Rust?

So I am not trying to suggest hiding a detail. I just am saying that it was not a useful point of reference.

@workingjubilee I see. the people you describe and used to belong to are one of the audiences that the docs serve and have to be accessible to. Other audiences exist as well, like people who know what stack and heap are and want to know how pin! relates to those two concepts: that's why I think the section is useful. I believe that the docs should be as jargon free as possible but one shouldn't sacrifice information content for it. I think stack and heap are pretty common things often taught in undergrad computer science classes and non-college programming courses. technically they might be jargon as the origin of the word isn't as connected with the concept itself as other terms in other places in programming (function, assignment, value, etc), but they are jargon of the most innocuous kind.

However, all this attention made me wonder now about the usually dubbed stack pinning part. I've thought it's an established term outside of rust. If it were, one could argue that it's important to mention the stack so that people who know stack pinning can easily reach this by google and also easily verify that it's the feature they are looking for. Looking up stack pinning doesn't give me any non-rust usage of such terms, outside of maybe pin_ptr. @danielhenrymantilla as you added these docs in #93176, what does the "usually" mean, which places have been calling it "stack" pinning? Are there books/lectures/papers/other languages that call it that way? Maybe one should remove the first sentence?

I guess https://docs.rs/futures/0.3.27/futures/macro.pin_mut.html and https://docs.rs/tokio/1.26.0/tokio/macro.pin.html may have been the main examples that gave me that impression

I wasn't taught about stack and heap despite taking programming courses. :/
I had to self-study that stuff. All of it.

( And the stack is a form of allocation anyways, just using hardware instructions... )

I don't mind using the words stack and heap per se, because I agree: for people who are familiar with that abstraction, they're a useful context. I just want to stress that docs should stand without them and address language-specific concerns first.

danielhenrymantilla

LGTM ✅

danielhenrymantilla · 2023-03-11T22:26:22Z

library/core/src/pin.rs

@@ -1003,22 +1003,26 @@ impl<P, U> CoerceUnsized<Pin<U>> for Pin<P> where P: CoerceUnsized<U> {}
 #[stable(feature = "pin", since = "1.33.0")]
 impl<P, U> DispatchFromDyn<Pin<U>> for Pin<P> where P: DispatchFromDyn<U> {}

-/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning[^1] a `value: T` _locally_[^2].
+/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning a value locally.


Nit: since the API is macro-based, its exact type signature is hard to know. I don't think we should remove the input type annotation in this sentence unless we were to add the whole signature elsewhere:

Suggested change

/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning a value locally.

/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning a `value: T` _locally_.

If, on the other hand, we were to write something like:

fn pin<T>(value: T) -> Pin<&'local mut T>

then we could indeed keep your sentence as-is (although I personally like the emphasis on locally)

Fair points about the type signature. I'm less sure about the emphasis on locally, as too much change in style hurts the read flow. The word is already quite prominent by virtue of being last in the sentence.

library/core/src/pin.rs

workingjubilee · 2023-03-12T03:49:32Z

library/core/src/pin.rs

-/// cheaper than pinning into a fresh heap allocation using [`Box::pin`]. Moreover, by virtue of not
-/// even needing an allocator, [`pin!`] is the main non-`unsafe` `#![no_std]`-compatible [`Pin`]
+/// On the other hand, local pinning using [`pin!`] is likely to be cheaper than
+/// pinning into a fresh heap allocation using [`Box::pin`]. Moreover, by virtue of not


No complaints about saying "heap allocation" here. The qualifier of "fresh" is what matters but it's fine to say that yes, Box will generally use some kind of "heap allocator".

This makes pin docs a little bit less jargon-y and easier to read, by * splitting up the sentences * making them less interrupted by punctuation * turning the footnotes into paragraphs, as they contain useful information that shouldn't be hidden in footnotes. Footnotes also interrupt the read flow. * other improvements and simplifications

Mark-Simulacrum · 2023-03-18T17:57:24Z

@bors r+ rollup

Thanks, this looks like an excellent cleanup.

bors · 2023-03-18T17:57:26Z

📌 Commit f663f09 has been approved by Mark-Simulacrum

It is now in the queue for this repository.

Rollup of 10 pull requests Successful merges: - rust-lang#104100 (Allow using `Range` as an `Iterator` in const contexts. ) - rust-lang#105793 (Add note for mismatched types because of circular dependencies) - rust-lang#108798 (move default backtrace setting to sys) - rust-lang#108829 (Use Edition 2021 :pat in matches macro) - rust-lang#108973 (Beautify pin! docs) - rust-lang#109003 (Add `useless_anonymous_reexport` lint) - rust-lang#109022 (read_buf_exact: on error, all read bytes are appended to the buffer) - rust-lang#109212 (fix: don't suggest similar method when unstable) - rust-lang#109243 (The name of NativeLib will be presented) - rust-lang#109324 (Implement FixedSizeEncoding for UnusedGenericParams.) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rustbot assigned Mark-Simulacrum Mar 10, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Mar 10, 2023

est31 force-pushed the pin_docs branch 3 times, most recently from 32fd14e to aee0c9c Compare March 10, 2023 11:53

Noratrieb mentioned this pull request Mar 11, 2023

Footnote links in short descriptions do not work #109024

Closed

T-Dark0 reviewed Mar 11, 2023

View reviewed changes

danielhenrymantilla approved these changes Mar 11, 2023

View reviewed changes

Noratrieb reviewed Mar 11, 2023

View reviewed changes

library/core/src/pin.rs Outdated Show resolved Hide resolved

workingjubilee reviewed Mar 12, 2023

View reviewed changes

est31 force-pushed the pin_docs branch from aee0c9c to 06ea86e Compare March 12, 2023 11:18

est31 force-pushed the pin_docs branch from 06ea86e to f663f09 Compare March 16, 2023 17:03

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 18, 2023

Dylan-DPC mentioned this pull request Mar 19, 2023

Rollup of 10 pull requests #109346

Merged

bors merged commit c8e112a into rust-lang:master Mar 19, 2023

rustbot added this to the 1.70.0 milestone Mar 19, 2023

est31 mentioned this pull request Sep 3, 2023

document ABI compatibility #115476

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Beautify pin! docs #108973

Beautify pin! docs #108973

est31 commented Mar 10, 2023

rustbot commented Mar 10, 2023

rustbot commented Mar 10, 2023

T-Dark0 Mar 11, 2023

est31 Mar 12, 2023

workingjubilee Mar 12, 2023 •

edited

Loading

est31 Mar 12, 2023

est31 Mar 12, 2023

workingjubilee Mar 12, 2023

est31 Mar 12, 2023 •

edited

Loading

danielhenrymantilla Mar 12, 2023

workingjubilee Mar 12, 2023 •

edited

Loading

danielhenrymantilla left a comment

danielhenrymantilla Mar 11, 2023

est31 Mar 12, 2023

workingjubilee Mar 12, 2023

Mark-Simulacrum commented Mar 18, 2023

bors commented Mar 18, 2023

	/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning a value locally.
	/// Constructs a <code>[Pin]<[&mut] T></code>, by pinning a `value: T` _locally_.

Beautify pin! docs #108973

Beautify pin! docs #108973

Conversation

est31 commented Mar 10, 2023

rustbot commented Mar 10, 2023

rustbot commented Mar 10, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

workingjubilee Mar 12, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

est31 Mar 12, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

workingjubilee Mar 12, 2023 • edited Loading

Choose a reason for hiding this comment

danielhenrymantilla left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mark-Simulacrum commented Mar 18, 2023

bors commented Mar 18, 2023

workingjubilee Mar 12, 2023 •

edited

Loading

est31 Mar 12, 2023 •

edited

Loading

workingjubilee Mar 12, 2023 •

edited

Loading