-
Notifications
You must be signed in to change notification settings - Fork 13.1k
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
Document the definition of the word "unwrap" as used by Rust #82383
Comments
@steveklabnik Do you have a sense of where in the documentation a canonical definition of the word "unwrap" might belong? The |
@rustbot modify labels: T-doc |
To be honest, I don't really understand why we would "define" a word. It's the name of a method, that's it. There's no special definition, or any strange usage. We don't write definitions of any other method names. The definition is the documentation of the unwrap method. |
I would not want to dedicate documentation to this either. The meaning in the context of Rust is 100% defined by the set of behaviors that have been given this name. When considering leveraging a preexisting name for a new behavior, the libs team evaluates how much the new behavior is in line with any old behaviors that already use the name. In my experience for those discussions a definition is not necessary, and maybe even counterproductive. For a word that is more obscure, the place to record the way we choose to use it in standard library APIs would be the standard library dev guide at https://std-dev-guide.rust-lang.org, but I think |
Ah, understood. Thank you for the clear explanation. I still think that understanding “what unwrap actually means” is a meaningful hole in the user experience, but I suppose that’s a job for a community blog post or talk. |
#68918 Don't use the word "unwrap" to describe "unwrap" methods
The English word "unwrap" is used in the name of numerous methods in
core
andstd
, but is not defined by the documentation and does not have a commonly accepted concrete definition in computer science. The everyday concept of "unwrapping" is not detailed enough to resolve questions about the precise meaning of the term as it is used in Rust.Existing methods:
Result
unwrap
,unwrap_or
,unwrap_or_else
,unwrap_or_default
,unwrap_err
Option
unwrap
,unwrap_or
,unwrap_or_else
,unwrap_or_default
,unwrap_none
(unstable)Rc
try_unwrap
Arc
try_unwrap
Based on this existing usage, I propose a definition:
Outstanding questions: Where is the most appropriate place to put a definition of "unwrap"? Is The Book canonical?
Previous discussion in:
#62633 Tracking issue for Option::expect_none(msg) and unwrap_none()
#73077 Stabilize Option::expect_none(msg) and Option::unwrap_none()
#77326 Stabilize
Option::unwrap_none
andOption::expect_none
#68849 Don't use the word 'unwrap' to describe core 'unwrap' functions
#68918 Don't use the word "unwrap" to describe "unwrap" methods
#23713 Make Option.unwrap documentation more precise
#19149 Rename unwrap functions to into_inner
#430 RFC: Finalizing more naming conventions
etc...
The text was updated successfully, but these errors were encountered: