create method overview docs for core::option and core::result by tlyu · Pull Request #86211 · rust-lang/rust

tlyu · 2021-06-11T03:48:16Z

The Option and Result types 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 different impl blocks, for example.

This is based on #86209, but those are small changes and unlikely to conflict.

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`.

rust-highfive · 2021-06-11T03:48:19Z

r? @kennytm

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

tlyu · 2021-06-11T03:57:30Z

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 Option overview is more complete than the one for Result. The similarity between the types would make it somewhat easy to copy parts of the work from one overview to the other.

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.

yaahc

This looks amazing btw, thank you for putting it together.

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 · 2021-06-22T20:55:30Z

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

(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.

tlyu · 2021-06-24T17:39:23Z

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.

yaahc · 2021-07-01T22:46:44Z

@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.

tlyu · 2021-07-02T00:19:40Z

@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.

yaahc · 2021-07-06T20:36:09Z

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!

joshtriplett · 2021-07-14T01:02:09Z

Looks great, thank you! One very minor nit, and otherwise r=me.

jyn514 · 2021-07-14T01:13:53Z

@bors r=joshtriplett

bors · 2021-07-14T01:13:54Z

📌 Commit 2b4a6aa has been approved by joshtriplett

bors · 2021-07-14T05:11:01Z

⌛ Testing commit 2b4a6aa with merge a08f25a...

bors · 2021-07-14T07:51:36Z

☀️ Test successful - checks-actions
Approved by: joshtriplett
Pushing a08f25a to master...

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``

…riplett create method overview docs for core::option and core::result The `Option` and `Result` types 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 different `impl` blocks, for example. This is based on rust-lang#86209, but those are small changes and unlikely to conflict.

tlyu added 3 commits June 10, 2021 22:30

fix wording in option doc
cb65b48
Fix some awkward wording in the `core::option` documentation in the "Options and pointers" section.

fix typo in option doc
4763377
Fix a typo/missed replacement in the documentation for `impl From<&Option<T>> for Option<&T>` in `core::option`.

method overviews for option and result
d54d59b

rust-highfive assigned kennytm Jun 11, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 11, 2021

programmerjake reviewed Jun 11, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

hellow554 reviewed Jun 11, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

hellow554 reviewed Jun 11, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

hellow554 reviewed Jun 11, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs

hellow554 reviewed Jun 11, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

tlyu added 3 commits June 11, 2021 11:34

updates based on reviews
7edc666
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.

more transformation methods in option overview
370f731

add modify-in-place methods to option overview
7265bef

yaahc reviewed Jun 11, 2021
View reviewed changes

This comment has been minimized.
Sign in to view

tlyu force-pushed the option-result-overviews branch from 02c082c to 834f4b7Compare June 12, 2021 21:33

tlyu added 3 commits June 14, 2021 21:42

add boolean operator example
1b58d93

add more to result overview
9a00fd0

Some<T> is not a type, etc
771f35c

rustbot added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Jun 22, 2021

tlyu marked this pull request as ready for review June 22, 2021 20:55

rustbot added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Jun 22, 2021

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/result.rs Outdated

joshtriplett reviewed Jun 23, 2021
View reviewed changes

Comment threadlibrary/core/src/result.rs Outdated

fix missing word
2b4a6aa

joshtriplett reviewed Jul 14, 2021
View reviewed changes

Comment threadlibrary/core/src/option.rs Outdated

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 Jul 14, 2021

bors added the merged-by-bors This PR was explicitly merged by bors. label Jul 14, 2021

bors merged commit a08f25a into rust-lang:masterJul 14, 2021

rustbot added this to the 1.55.0 milestone Jul 14, 2021

RalfJung mentioned this pull request Jul 16, 2021
fix typo in compile_fail doctest #87183
Merged

tlyu deleted the option-result-overviews branch July 22, 2021 23:12

albertlarsan68 mentioned this pull request Dec 13, 2022
Rustdoc does not format ASCII art containing ### at the start of a line correctly #105527
Closed

scottmcm mentioned this pull request Apr 28, 2026
Delete the 12 year old fixme #155913
Merged

Uh oh!

Uh oh!

Conversation

tlyu commented Jun 11, 2021

Uh oh!

rust-highfive commented Jun 11, 2021

Uh oh!

tlyu commented Jun 11, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yaahc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

tlyu commented Jun 22, 2021• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tlyu commented Jun 24, 2021

Uh oh!

yaahc commented Jul 1, 2021

Uh oh!

tlyu commented Jul 2, 2021

Uh oh!

yaahc commented Jul 6, 2021

Uh oh!

Uh oh!

joshtriplett commented Jul 14, 2021

Uh oh!

jyn514 commented Jul 14, 2021

Uh oh!

bors commented Jul 14, 2021

Uh oh!

bors commented Jul 14, 2021

Uh oh!

bors commented Jul 14, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

yaahc left a comment •
edited
Loading

tlyu commented Jun 22, 2021•
edited
Loading