Add --scrape-tests option to rustdoc to scrape functions marked #[test] by willcrichton · Pull Request #93497 · rust-lang/rust (original) (raw)
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 andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation27 Commits1 Checks0 Files changed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
Relevant to the rustdoc team, which will review and decide on the PR/issue.
label
This was referenced
Jan 31, 2022
In my opinion it's not necessarily the "right" usage. In tests you use items in order to make sure they work under any circumstance. Not sure if it's good to be used as an example.
In my opinion it's not necessarily the "right" usage. In tests you use items in order to make sure they work under any circumstance. Not sure if it's good to be used as an example.
Note that this PR makes it possible for Rustdoc to scrape examples from tests. The proposed default is still that only examples and library code are used. But this way if someone wants to include tests as examples, then they can. That decision is left to the library author.
I stand on my position by if it's not enabled by default, then let's say I'm neutral.
I thought scrape-examples only works on examples/? Aren't #[test] functions usually in the crate itself?
They can be inside the crate source code and in their own folder.
Examples can theoretically be scraped from any source file in your Cargo workspace. The default is just the examples/ directory.
Oh, so scrape-examples already supports scraping e.g. library source code if you tell it to?
If there are no other objections to this PR, it would be good to get it merged so I can get tests passing on rust-lang/cargo#10343.
This is quite an extension so I'd prefer to have everyone on the team agreeing with it first.
cc @rust-lang/rustdoc
I support this PR. A crate might be intended for use in test cases, so it makes sense to have example code that uses #[test], and you ought to be able up scrape it.
If other words, I think being example code and being test code are orthogonal.
I don't agree with your point of view but I agree on the fact that users should be able to include their tests into the "scraped examples". For me, tests are meant to check that your code works whereas examples are meant to show how to use your API.
Maybe this should be a different flag, e.g. --include-tests? --test is used to run tests, but AFAICT this PR makes it so it's also used when building docs? That seems wrong.
This PR only affects the case where the user is scraping examples, not the general documentation code paths. But I can create a new flag if you like.
This PR only affects the case where the user is scraping examples, not the general documentation code paths. But I can create a new flag if you like.
Yeah, using the flag seems confusing to me.
Could you squash your commits btw?
Pass --test flag through rustdoc to rustc so #[test] functions can be scraped Pass --test flag through rustdoc to rustc so #[test] functions can be scraped
Just noting that now that it's a new unstable flag, an FCP shouldn't be necessary.
I just added some documentation for the flag as well.
Looks good to me now, thanks!
I'm waiting for one last review from @camelid. If they don't see anything else, then let's r+. :)
As long as this PR only adds behavior behind a new unstable flag, I have no objections.
📌 Commit fbbcb08 has been approved by GuillaumeGomez
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
bors added a commit to rust-lang-ci/rust that referenced this pull request
…askrgr
Rollup of 10 pull requests
Successful merges:
- rust-lang#89892 (Suggest
impl Traitreturn type when incorrectly using a generic return type) - rust-lang#91675 (Add MemTagSanitizer Support)
- rust-lang#92806 (Add more information to
impl Traiterror) - rust-lang#93497 (Pass
--testflag through rustdoc to rustc so#[test]functions can be scraped) - rust-lang#93814 (mips64-openwrt-linux-musl: correct soft-foat)
- rust-lang#93847 (kmc-solid: Use the filesystem thread-safety wrapper)
- rust-lang#93877 (asm: Allow the use of r8-r14 as clobbers on Thumb1)
- rust-lang#93892 (Only mark projection as ambiguous if GAT substs are constrained)
- rust-lang#93915 (Implement --check-cfg option (RFC 3013), take 2)
- rust-lang#93953 (Add the
known-bugtest directive, use it, and do some cleanup)
Failed merges:
r? @ghost
@rustbot modify labels: rollup
Note
This PR's title is actually inaccurate since the contents changed after creation. It actually adds a new unstable flag and doesn't change the existing --test flag's behavior.
Pass Add --test flag through rustdoc to rustc so #[test] functions can be scraped--scrape-tests option to rustdoc to scrape functions marked #[test]
Good point. I updated the title.
Labels
Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Relevant to the rustdoc team, which will review and decide on the PR/issue.