Skip to content

implicit Option-returning doctests #61279

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom
Merged
merged 1 commit into from
May 30, 2019
Merged

implicit Option-returning doctests #61279

merged 1 commit into from
May 30, 2019

Conversation

llogiq
Copy link
Contributor

@llogiq llogiq commented May 28, 2019

This distinguishes Option and Result-returning doctests with implicit main method, where the former tests must end with Some(()).

Open question: Does this need a feature gate?

r? @GuillaumeGomez

@llogiq
implicit Option-returning doctests
6bb6c00 
This distinguishes `Option` and `Result`-returning doctests with
implicit `main` method, where the former tests must end with
`Some(())`.
@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 28, 2019
@GuillaumeGomez
Copy link
Member

Looks good to me except the backquote stuff. I don't think a feature gate is needed in here so just r=me once you've updated. Thanks!

@GuillaumeGomez
Copy link
Member

@bors: r+

@bors
Copy link
Collaborator

bors commented May 30, 2019

📌 Commit 6bb6c00 has been approved by GuillaumeGomez

@bors 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 May 30, 2019
Centril added a commit to Centril/rust that referenced this pull request May 30, 2019
@Centril
Rollup merge of rust-lang#61279 - llogiq:implicit-option-main-doctest…
07d0b57 
…s, r=GuillaumeGomez

implicit `Option`-returning doctests

This distinguishes `Option` and `Result`-returning doctests with implicit `main` method, where the former tests must end with `Some(())`.

Open question: Does this need a feature gate?

r? @GuillaumeGomez
@Centril Centril mentioned this pull request May 30, 2019
Merged
bors added a commit that referenced this pull request May 30, 2019
@bors
Auto merge of #61343 - Centril:rollup-dzsuo01, r=Centril
8e2b2eb 
Rollup of 11 pull requests

Successful merges:

 - #60802 (upgrade rustdoc's `pulldown-cmark` to 0.5.2)
 - #60839 (Fix ICE with struct ctors and const generics.)
 - #60850 (Stabilize RefCell::try_borrow_unguarded)
 - #61231 (Fix linkage diagnostic so it doesn't ICE for external crates)
 - #61244 (Box::into_vec: use Box::into_raw instead of mem::forget)
 - #61279 (implicit `Option`-returning doctests)
 - #61280 (Revert "Disable solaris target since toolchain no longer builds")
 - #61284 (Update all s3 URLs used on CI with subdomains)
 - #61321 (libsyntax: introduce 'fn is_keyword_ahead(dist, keywords)'.)
 - #61322 (ci: display more debug information in the init_repo script)
 - #61333 (Fix ICE with APIT in a function with a const parameter)

Failed merges:

 - #61304 (Speed up Azure CI installing Windows dependencies)

r? @ghost
bors added a commit that referenced this pull request May 30, 2019
@bors
Auto merge of #61343 - Centril:rollup-dzsuo01, r=Centril
aee7012 
Rollup of 11 pull requests

Successful merges:

 - #60802 (upgrade rustdoc's `pulldown-cmark` to 0.5.2)
 - #60839 (Fix ICE with struct ctors and const generics.)
 - #60850 (Stabilize RefCell::try_borrow_unguarded)
 - #61231 (Fix linkage diagnostic so it doesn't ICE for external crates)
 - #61244 (Box::into_vec: use Box::into_raw instead of mem::forget)
 - #61279 (implicit `Option`-returning doctests)
 - #61280 (Revert "Disable solaris target since toolchain no longer builds")
 - #61284 (Update all s3 URLs used on CI with subdomains)
 - #61321 (libsyntax: introduce 'fn is_keyword_ahead(dist, keywords)'.)
 - #61322 (ci: display more debug information in the init_repo script)
 - #61333 (Fix ICE with APIT in a function with a const parameter)

Failed merges:

 - #61304 (Speed up Azure CI installing Windows dependencies)

r? @ghost
@bors bors merged commit 6bb6c00 into rust-lang:master May 30, 2019
@Centril Centril added relnotes Marks issues that should be documented in the release notes of the next release. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels May 30, 2019
@ollie27
Copy link
Member

ollie27 commented May 30, 2019

Open question: Does this need a feature gate?

It would have been nice to at least have a FCP.

I don't really agree with this. Option<()> doesn't implement Termination so we're no longer just wrapping code in a main function any more.

@GuillaumeGomez
Copy link
Member

@ollie27: For me it's not really an issue. However, do you think we should implement Termination for Option<()>?

@GuillaumeGomez GuillaumeGomez mentioned this pull request May 30, 2019
Closed
@ollie27
Copy link
Member

ollie27 commented May 30, 2019

Well what does the rest of @rust-lang/rustdoc think about this change?

@llogiq llogiq deleted the implicit-option-main-doctests branch May 30, 2019 18:57
@llogiq
Copy link
Contributor Author

llogiq commented May 30, 2019

@ollie27 Interesting. For the record, I personally think we should add a Termination impl for Option<()>, if only to get it to parity with Result<(), impl Error>. But this is about doctests without an explicit main method, so how it works is essentially an implementation detail.

The goal of my previous ? related change (and also this one) is to make rust doctests less error-handling-laden. Because often you don't really care that much about the Result (and certainly not about how you can unwrap them) but you need the Ok(_) part to get to the point.

Using ? gets the job done with minimal decorum and shows that there is an error path one needs to keep in mind. On the other hand, .unwrap() has the benefit of being copy+paste-able into other code without requiring a special return type, but I think good error messages will reduce this particular papercut to an acceptable size.

@GuillaumeGomez
Copy link
Member

I actually opened #61360 to start a discussion about it. It *seems* like we'd want to have Termination implemented for Option<()> but that's clearly up to debate. I invite you to take a look at the PR discussion directly. :)

@QuietMisdreavus
Copy link
Member

Late to the party, but I'm actually opposed to this, since Option<()> doesn't implement Termination. The ongoing discussion in #61360 seems to not be strongly in favor (though also only mildly against, either), so if that is closed with the decision to not implement Termination for Option<()>, i would prefer that this be reverted. I don't feel like this is a compelling-enough feature to further complicate the model of doctests.

All our messaging up to this point has been that doctests wrap fn main around loose expressions, and our support of returning Result builds on that because of its use in fn main generally. Supporting returning Option breaks this model and creates something doctest-specific. Now we don't just wrap fn main around doctests; we create a bubble for loose expressions to exist in, that shares some resemblance to fn main but doesn't 100% match up.

In effect, i pretty much agree with this comment from the other thread. There are other things we can suggest people to do instead of supporting Option<()> directly.

QuietMisdreavus
QuietMisdreavus reviewed Jun 10, 2019
View reviewed changes
src/doc/rustdoc/src/documentation-tests.md
```ignore
/// ```
/// let _ = &[].iter().next()?;
///# Some(())
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, this line should have added a space between /// #, since historically having single lines without that leading space has messed up rustdoc's Markdown parser.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @llogiq

@GuillaumeGomez GuillaumeGomez mentioned this pull request Jul 1, 2019
Merged
bors added a commit that referenced this pull request Jul 1, 2019
@bors
Auto merge of #62267 - GuillaumeGomez:revert-implicit-option-return, …
17e62f7 
…r=Centril

Revert "implicit `Option`-returning doctests"

Reverts #61279 as discussed in #61360.

cc @Centril
@Centril Centril removed the relnotes Marks issues that should be documented in the release notes of the next release. label Jul 21, 2019
@Centril
Copy link
Contributor

Centril commented Jul 21, 2019

Removing relnotes label since this was reverted.

# for free to join this conversation on GitHub. Already have an account? # to comment
Reviewers

@GuillaumeGomez GuillaumeGomez GuillaumeGomez left review comments

@QuietMisdreavus QuietMisdreavus QuietMisdreavus left review comments

Assignees

@GuillaumeGomez GuillaumeGomez

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@llogiq @GuillaumeGomez @bors @ollie27 @QuietMisdreavus @Centril @rust-highfive