create method overview docs for core::option and core::result #86211
Conversation
Fix some awkward wording in the `core::option` documentation in the "Options and pointers" section.
Fix a typo/missed replacement in the documentation for `impl From<&Option<T>> for Option<&T>` in `core::option`.
|
r? @kennytm (rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
This is still a work in progress. I wanted to get something out there for early feedback before I got too far into it. The |
Fix an error in `map_or_else`. Use more descriptive text for "don't care" in truth tables. Make minor corrections to truth tables. Rename `makeiter` to `make_iter` in examples.
This comment has been minimized.
This comment has been minimized.
Make minor wording changes in a few places. Move `filter` to the "transformations" section. Add `zip` methods to the "transformations" section. Clarify the section about `Option` iterators, and add a section about collecting into `Option`. Clarify that for `Result`, `or` and `or_else` can also produce a `Result` having a different type.
tlyu
force-pushed
the
option-result-overviews
branch
from
02c082c
to
834f4b7
Compare
|
I think this is about ready for review. I think the overviews cover most of the methods of interest, but aren't exhaustive. The main other thing I might want to do is to take @yaahc's suggestion about reordering the lazy-evaluated boolean methods first, and explain the short-circuiting in more detail. But maybe that could be a separate PR? @rustbot label +A-docs +T-libs |
rustbot
added
the
T-libs
rustbot
added
the
A-docs
(Most of these are from a review by joshtriplett. Thanks!) Fix errors in `as_pin_ref` and `as_pin_mut` in the "Adapters for working with references" overview. Reword some headings about transformation methods. Reclassify `map`, `map_or`, `map_or_else`, `map_err`, etc. to more accurately reflect which variants they transform. Document `Debug` requirement for `get_or_insert_default`. Reword text about `take` and `replace` to be more accurate. Add examples for the `Product` and `Sum` traits. Also: Move link reference definitions closer to their uses. Warn about making link reference definintions for `err` and `ok`. Avoid making other link reference definitions that might conflict in the future (foreign methods that share a name with local ones, etc.) Write out the generics of `Option` and `Result` when the following text refers to the type parameters.
|
Thanks for the review! I've pushed an update that should address these. (Also fixed a few other small things I noticed along the way.) Please let me know what you think. |
|
@tlyu could you mark the comments as resolved that you've already dealt with? Otherwise it's hard to know which comments if any still need attention. |
Thanks! Done. I also pushed a minor update to add a missing word that I noticed while re-reviewing the comments. |
|
Awesome, I went ahead and resolved the last two comments which you'd given responses to that I felt happy with upon review. I'm happy with this PR and ready to r+ it right now assuming @joshtriplett is also happy with it. Thank you again for this wonderfully detailed addition @tlyu! |
|
Looks great, thank you! One very minor nit, and otherwise r=me. |
|
@bors r=joshtriplett |
|
📌 Commit 2b4a6aa has been approved by |
bors
added
S-waiting-on-bors
|
☀️ Test successful - checks-actions |
fix typo in compile_fail doctest Fixes a typo introduced by rust-lang#86211. For some reason this typo makes Miri go all crazy when running libcore doctests (rust-lang/miri#1852). Kudos to `@hyd-dev` for noticing the typo. Cc `@tlyu` `@joshtriplett`
fix typo in compile_fail doctest Fixes a typo introduced by rust-lang#86211. For some reason this typo makes Miri go all crazy when running libcore doctests (rust-lang/miri#1852). Kudos to ``@hyd-dev`` for noticing the typo. Cc ``@tlyu`` ``@joshtriplett``
The
OptionandResulttypes have large lists of methods. They each could use an overview page of methods grouped by category. These proposed overviews include "truth tables" for the underappreciated boolean operators/combinators of these types. The methods are already somewhat categorized in the source, but some logical groupings are broken up by the necessities of putting related methods in differentimplblocks, for example.This is based on #86209, but those are small changes and unlikely to conflict.