I think most people get a partial idea of what Pin is fairly quickly when they try, but that's part of the problem.
They struggle a lot more with Unpin, and particularly the dynamics as code changes. This comes up more often than in probably should in an async context. (re. "should", the problem is it shows up because of closure changes most often, and the errors (last I was teaching) take the user to the wrong place, typically the just need to allocate, but there's no practicum on their error understanding path, see below).
Users are integrating a change of some kind, get a compiler error and then struggle even further to really understand when and how the unpin marker exists, but a change, potentially at a fair distance from the code that they're editing, is now making compilation time demands that they both understand and address the issue.
When those users enter the argument with rustc, they come to a page that starts with:
Implementing the Unpin trait for T expresses the fact that T is pinning-agnostic: it shall not expose nor rely on any pinning guarantees. This, in turn, means that a Pin-wrapped pointer to such a type can feature a fully unrestricted API. In other words, if T: Unpin, a value of type T will not be bound by the invariants which pinning otherwise offers, even when “pinned” by a Pin<Ptr> pointing at it. When a value of type T is pointed at by a Pin<Ptr>, Pin will not restrict access to the pointee value like it normally would, thus allowing the user to do anything that they normally could with a non-Pin-wrapped Ptr to that value.
Now this is reasonable documentation if you're in the thick of this universe, but to the average reader this is full of self-referential definition. When you have a weak understanding of Pin, then Unpin being defined in terms of Pin makes no sense, it's the same as Pin being defined in terms of Pin. All of this documentation needs to shift to a "systems engineering" or "in practice" basis first, and follow with theory. Most users give up with the docs before the second sentence they can't understand.
All of the cleverness (reliance on a priori theory) in the docs for these core types needs to be moved out of the way for most readers - replaced by much simpler terminology and practicum suitable for the average knuckledragger. Normal people who end up here in practice are on average already at saturation point for working memory, they have "no stack space left" for trying to unpack language theory.
I agree that this definition of Unpin should be improved, but I'm confused about the scenario you're describing. When does a user encounter an error because of Unpin?
Is it just that they use an API which requires Unpin? If so, what APIs do you encounter causing the issue most often?
They struggle a lot more with Unpin, and particularly the dynamics as code changes. This comes up more often than in probably should in an async context. (re. "should", the problem is it shows up because of closure changes most often, and the errors (last I was teaching) take the user to the wrong place, typically the just need to allocate, but there's no practicum on their error understanding path, see below).
Users are integrating a change of some kind, get a compiler error and then struggle even further to really understand when and how the unpin marker exists, but a change, potentially at a fair distance from the code that they're editing, is now making compilation time demands that they both understand and address the issue.
When those users enter the argument with rustc, they come to a page that starts with:
Now this is reasonable documentation if you're in the thick of this universe, but to the average reader this is full of self-referential definition. When you have a weak understanding of Pin, then Unpin being defined in terms of Pin makes no sense, it's the same as Pin being defined in terms of Pin. All of this documentation needs to shift to a "systems engineering" or "in practice" basis first, and follow with theory. Most users give up with the docs before the second sentence they can't understand.All of the cleverness (reliance on a priori theory) in the docs for these core types needs to be moved out of the way for most readers - replaced by much simpler terminology and practicum suitable for the average knuckledragger. Normal people who end up here in practice are on average already at saturation point for working memory, they have "no stack space left" for trying to unpack language theory.