-
Notifications
You must be signed in to change notification settings - Fork 117
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
2024: Add rustdoc combined doctests #320
Conversation
src/rust-2024/rustdoc-doctests.md
Outdated
* Uses the [`compile_fail`][tags] language tag, which indicates that the example fails to compile. | ||
* Uses the [`edition`][tags], which indicates the edition of the example.[^edition-tag] | ||
* Uses global attributes like the [`global_allocator`] attribute, which could potentially interfere with other tests. | ||
* Defines any crate-wide attributes (like `#![deny(unused)]`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually the deny
, warn
and allow
lint levels are not preventing a doctests to be merged. It's actually the only inner attribute in this case. ;)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I didn't catch that, thanks! I switched it to the feature
attribute which I believe does always prevent it from being combined.
|
||
```rust | ||
//! ``` | ||
//! let location = std::panic::Location::caller(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perfect example. I think it's the only case where code wasn't working in merged doctest.
src/rust-2024/rustdoc-doctests.md
Outdated
|
||
## Migration | ||
|
||
There is no automatic migration to determine which doctests need to be annotated with the `standalone` tag. You will need to update your crate to the 2024 Edition and then run your documentation tests and see if any of them fail. If they do fail, you will need to analyze whether the test can be rewritten to be compatible with the combined approach, or add the `standalone` tag to retain the previous behavior. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would "tone it down" a bit. In all crates we tested, we only found one case (in libcore
) which didn't work with merged doctests. I think maybe something "It's very unlikely to happen but some doctests might not worked when merged. The only way to know it is to run them with the 2024 edition. ...". What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, I thought about adding something along those lines. I added a few sentences to emphasize that it is unlikely to be an issue.
@@ -45,7 +45,7 @@ In some situations it is not possible for rustdoc to combine examples in a singl | |||
* Uses the [`compile_fail`][tags] language tag, which indicates that the example fails to compile. | |||
* Uses the [`edition`][tags], which indicates the edition of the example.[^edition-tag] | |||
* Uses global attributes like the [`global_allocator`] attribute, which could potentially interfere with other tests. | |||
* Defines any crate-wide attributes (like `#![deny(unused)]`). | |||
* Defines any crate-wide attributes (like `#![feature(...)]`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
Looks all good to me, thanks! |
87dad99
to
91a2bf7
Compare
Update books ## rust-lang/book 4 commits in 04bc1396bb857f35b5dda1d773c9571e1f253304..e7d217be2a75ef1753f0988d6ccaba4d7e376259 2024-08-14 01:19:47 UTC to 2024-08-13 16:51:00 UTC - Backport/forward port ch12 (rust-lang/book#4008) - Found some more things to fix in ch7; I forgot to update the snapshot (rust-lang/book#4007) - Remove redundant sentence. Send to nostarch (rust-lang/book#4006) - Fix: typo (rust-lang/book#4003) ## rust-lang/edition-guide 5 commits in aeeb287d41a0332c210da122bea8e0e91844ab3e..eeba2cb9c37ab74118a4fb5e5233f7397e4a91f8 2024-08-19 23:28:06 UTC to 2024-08-15 15:12:33 UTC - 2024: Add rustdoc combined doctests (rust-lang/edition-guide#320) - Update for unsafe attributes stabilization (rust-lang/edition-guide#319) - 2024: Add macro-fragment-specifiers. (rust-lang/edition-guide#312) - Fix deprecated_safe_2024 link (rust-lang/edition-guide#317) - Add 2024 unsafe functions (rust-lang/edition-guide#304) ## rust-embedded/book 1 commits in 019f3928d8b939ec71b63722dcc2e46330156441..ff5d61d56f11e1986bfa9652c6aff7731576c37d 2024-08-20 07:26:19 UTC to 2024-08-20 07:26:19 UTC - Use aligned address to demonstrate HardFault (rust-embedded/book#374) ## rust-lang/nomicon 1 commits in 6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9..14649f15d232d509478206ee9ed5105641aa60d0 2024-08-14 14:49:09 UTC to 2024-08-14 14:49:09 UTC - CI: Switch to merge queue (rust-lang/nomicon#459) ## rust-lang/reference 14 commits in 62cd0df95061ba0ac886333f5cd7f3012f149da1..0668397076da350c404dadcf07b6cbc433ad3743 2024-08-11 21:06:12 +0000 to 2024-08-27 21:47:20 +0000 - Update enum.md (rust-lang/reference#1354) - Be consistent about how "Edition differences" is capitalized (rust-lang/reference#1586) - Sync denied lints with upstream (rust-lang/reference#1589) - const_eval: update for const-fn float stabilization (rust-lang/reference#1566) - Add spec identifier syntax to destructors.md (rust-lang/reference#1571) - Say that `pub(in path)` can't depend on `use` statements (rust-lang/reference#1559) - bytes inside implicitly const-promoted expressions are immutable (rust-lang/reference#1554) - Tweak `repr(transparent)` to mention requiring *at most* one non-1-ZST (rust-lang/reference#1568) - operator expressions: add &raw (rust-lang/reference#1567) - Rewrite the automatic std link translation, and switch to automatic links (rust-lang/reference#1578) - Add some basic docs for unsafe attrs (rust-lang/reference#1539) - don't capitalize Undefined Behavior (rust-lang/reference#1575) - add the `const` operand to docs for inline assembly (rust-lang/reference#1556) - Typo: 'a' to 'an' in type-coercions.md (rust-lang/reference#1572) ## rust-lang/rust-by-example 1 commits in 8f94061936e492159f4f6c09c0f917a7521893ff..859786c5bc99301bbc22fc631a5c2b341860da08 2024-08-26 10:30:48 UTC to 2024-08-26 10:30:48 UTC - Update primitives.md with examples (rust-lang/rust-by-example#1878) ## rust-lang/rustc-dev-guide 7 commits in 43d8378..fa928a6 2024-08-26 14:46:50 UTC to 2024-08-12 21:07:49 UTC - Fix x.py reference (rust-lang/rustc-dev-guide#2049) - Update `stabilization_guide.md` (rust-lang/rustc-dev-guide#2034) - Explain the internal `#[rustc_*]` TEST attributes used for debugging and inside tests (rust-lang/rustc-dev-guide#2046) - missing char (rust-lang/rustc-dev-guide#2047) - Replace direct http links to rustc-dev-guide.rust-lang.org (rust-lang/rustc-dev-guide#2044) - Update index.html, 39. The MIR: fix typo (rust-lang/rustc-dev-guide#2043) - Update LLVM docs (rust-lang/rustc-dev-guide#2039)
Update books ## rust-lang/book 4 commits in 04bc1396bb857f35b5dda1d773c9571e1f253304..e7d217be2a75ef1753f0988d6ccaba4d7e376259 2024-08-14 01:19:47 UTC to 2024-08-13 16:51:00 UTC - Backport/forward port ch12 (rust-lang/book#4008) - Found some more things to fix in ch7; I forgot to update the snapshot (rust-lang/book#4007) - Remove redundant sentence. Send to nostarch (rust-lang/book#4006) - Fix: typo (rust-lang/book#4003) ## rust-lang/edition-guide 5 commits in aeeb287d41a0332c210da122bea8e0e91844ab3e..eeba2cb9c37ab74118a4fb5e5233f7397e4a91f8 2024-08-19 23:28:06 UTC to 2024-08-15 15:12:33 UTC - 2024: Add rustdoc combined doctests (rust-lang/edition-guide#320) - Update for unsafe attributes stabilization (rust-lang/edition-guide#319) - 2024: Add macro-fragment-specifiers. (rust-lang/edition-guide#312) - Fix deprecated_safe_2024 link (rust-lang/edition-guide#317) - Add 2024 unsafe functions (rust-lang/edition-guide#304) ## rust-embedded/book 1 commits in 019f3928d8b939ec71b63722dcc2e46330156441..ff5d61d56f11e1986bfa9652c6aff7731576c37d 2024-08-20 07:26:19 UTC to 2024-08-20 07:26:19 UTC - Use aligned address to demonstrate HardFault (rust-embedded/book#374) ## rust-lang/nomicon 1 commits in 6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9..14649f15d232d509478206ee9ed5105641aa60d0 2024-08-14 14:49:09 UTC to 2024-08-14 14:49:09 UTC - CI: Switch to merge queue (rust-lang/nomicon#459) ## rust-lang/reference 14 commits in 62cd0df95061ba0ac886333f5cd7f3012f149da1..0668397076da350c404dadcf07b6cbc433ad3743 2024-08-11 21:06:12 +0000 to 2024-08-27 21:47:20 +0000 - Update enum.md (rust-lang/reference#1354) - Be consistent about how "Edition differences" is capitalized (rust-lang/reference#1586) - Sync denied lints with upstream (rust-lang/reference#1589) - const_eval: update for const-fn float stabilization (rust-lang/reference#1566) - Add spec identifier syntax to destructors.md (rust-lang/reference#1571) - Say that `pub(in path)` can't depend on `use` statements (rust-lang/reference#1559) - bytes inside implicitly const-promoted expressions are immutable (rust-lang/reference#1554) - Tweak `repr(transparent)` to mention requiring *at most* one non-1-ZST (rust-lang/reference#1568) - operator expressions: add &raw (rust-lang/reference#1567) - Rewrite the automatic std link translation, and switch to automatic links (rust-lang/reference#1578) - Add some basic docs for unsafe attrs (rust-lang/reference#1539) - don't capitalize Undefined Behavior (rust-lang/reference#1575) - add the `const` operand to docs for inline assembly (rust-lang/reference#1556) - Typo: 'a' to 'an' in type-coercions.md (rust-lang/reference#1572) ## rust-lang/rust-by-example 1 commits in 8f94061936e492159f4f6c09c0f917a7521893ff..859786c5bc99301bbc22fc631a5c2b341860da08 2024-08-26 10:30:48 UTC to 2024-08-26 10:30:48 UTC - Update primitives.md with examples (rust-lang/rust-by-example#1878) ## rust-lang/rustc-dev-guide 7 commits in 43d8378..fa928a6 2024-08-26 14:46:50 UTC to 2024-08-12 21:07:49 UTC - Fix x.py reference (rust-lang/rustc-dev-guide#2049) - Update `stabilization_guide.md` (rust-lang/rustc-dev-guide#2034) - Explain the internal `#[rustc_*]` TEST attributes used for debugging and inside tests (rust-lang/rustc-dev-guide#2046) - missing char (rust-lang/rustc-dev-guide#2047) - Replace direct http links to rustc-dev-guide.rust-lang.org (rust-lang/rustc-dev-guide#2044) - Update index.html, 39. The MIR: fix typo (rust-lang/rustc-dev-guide#2043) - Update LLVM docs (rust-lang/rustc-dev-guide#2039)
Update books ## rust-lang/book 4 commits in 04bc1396bb857f35b5dda1d773c9571e1f253304..e7d217be2a75ef1753f0988d6ccaba4d7e376259 2024-08-14 01:19:47 UTC to 2024-08-13 16:51:00 UTC - Backport/forward port ch12 (rust-lang/book#4008) - Found some more things to fix in ch7; I forgot to update the snapshot (rust-lang/book#4007) - Remove redundant sentence. Send to nostarch (rust-lang/book#4006) - Fix: typo (rust-lang/book#4003) ## rust-lang/edition-guide 5 commits in aeeb287d41a0332c210da122bea8e0e91844ab3e..eeba2cb9c37ab74118a4fb5e5233f7397e4a91f8 2024-08-19 23:28:06 UTC to 2024-08-15 15:12:33 UTC - 2024: Add rustdoc combined doctests (rust-lang/edition-guide#320) - Update for unsafe attributes stabilization (rust-lang/edition-guide#319) - 2024: Add macro-fragment-specifiers. (rust-lang/edition-guide#312) - Fix deprecated_safe_2024 link (rust-lang/edition-guide#317) - Add 2024 unsafe functions (rust-lang/edition-guide#304) ## rust-embedded/book 1 commits in 019f3928d8b939ec71b63722dcc2e46330156441..ff5d61d56f11e1986bfa9652c6aff7731576c37d 2024-08-20 07:26:19 UTC to 2024-08-20 07:26:19 UTC - Use aligned address to demonstrate HardFault (rust-embedded/book#374) ## rust-lang/nomicon 1 commits in 6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9..14649f15d232d509478206ee9ed5105641aa60d0 2024-08-14 14:49:09 UTC to 2024-08-14 14:49:09 UTC - CI: Switch to merge queue (rust-lang/nomicon#459) ## rust-lang/reference 14 commits in 62cd0df95061ba0ac886333f5cd7f3012f149da1..0668397076da350c404dadcf07b6cbc433ad3743 2024-08-11 21:06:12 +0000 to 2024-08-27 21:47:20 +0000 - Update enum.md (rust-lang/reference#1354) - Be consistent about how "Edition differences" is capitalized (rust-lang/reference#1586) - Sync denied lints with upstream (rust-lang/reference#1589) - const_eval: update for const-fn float stabilization (rust-lang/reference#1566) - Add spec identifier syntax to destructors.md (rust-lang/reference#1571) - Say that `pub(in path)` can't depend on `use` statements (rust-lang/reference#1559) - bytes inside implicitly const-promoted expressions are immutable (rust-lang/reference#1554) - Tweak `repr(transparent)` to mention requiring *at most* one non-1-ZST (rust-lang/reference#1568) - operator expressions: add &raw (rust-lang/reference#1567) - Rewrite the automatic std link translation, and switch to automatic links (rust-lang/reference#1578) - Add some basic docs for unsafe attrs (rust-lang/reference#1539) - don't capitalize Undefined Behavior (rust-lang/reference#1575) - add the `const` operand to docs for inline assembly (rust-lang/reference#1556) - Typo: 'a' to 'an' in type-coercions.md (rust-lang/reference#1572) ## rust-lang/rust-by-example 1 commits in 8f94061936e492159f4f6c09c0f917a7521893ff..859786c5bc99301bbc22fc631a5c2b341860da08 2024-08-26 10:30:48 UTC to 2024-08-26 10:30:48 UTC - Update primitives.md with examples (rust-lang/rust-by-example#1878) ## rust-lang/rustc-dev-guide 7 commits in 43d8378..fa928a6 2024-08-26 14:46:50 UTC to 2024-08-12 21:07:49 UTC - Fix x.py reference (rust-lang/rustc-dev-guide#2049) - Update `stabilization_guide.md` (rust-lang/rustc-dev-guide#2034) - Explain the internal `#[rustc_*]` TEST attributes used for debugging and inside tests (rust-lang/rustc-dev-guide#2046) - missing char (rust-lang/rustc-dev-guide#2047) - Replace direct http links to rustc-dev-guide.rust-lang.org (rust-lang/rustc-dev-guide#2044) - Update index.html, 39. The MIR: fix typo (rust-lang/rustc-dev-guide#2043) - Update LLVM docs (rust-lang/rustc-dev-guide#2039)
Rollup merge of rust-lang#129617 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 4 commits in 04bc1396bb857f35b5dda1d773c9571e1f253304..e7d217be2a75ef1753f0988d6ccaba4d7e376259 2024-08-14 01:19:47 UTC to 2024-08-13 16:51:00 UTC - Backport/forward port ch12 (rust-lang/book#4008) - Found some more things to fix in ch7; I forgot to update the snapshot (rust-lang/book#4007) - Remove redundant sentence. Send to nostarch (rust-lang/book#4006) - Fix: typo (rust-lang/book#4003) ## rust-lang/edition-guide 5 commits in aeeb287d41a0332c210da122bea8e0e91844ab3e..eeba2cb9c37ab74118a4fb5e5233f7397e4a91f8 2024-08-19 23:28:06 UTC to 2024-08-15 15:12:33 UTC - 2024: Add rustdoc combined doctests (rust-lang/edition-guide#320) - Update for unsafe attributes stabilization (rust-lang/edition-guide#319) - 2024: Add macro-fragment-specifiers. (rust-lang/edition-guide#312) - Fix deprecated_safe_2024 link (rust-lang/edition-guide#317) - Add 2024 unsafe functions (rust-lang/edition-guide#304) ## rust-embedded/book 1 commits in 019f3928d8b939ec71b63722dcc2e46330156441..ff5d61d56f11e1986bfa9652c6aff7731576c37d 2024-08-20 07:26:19 UTC to 2024-08-20 07:26:19 UTC - Use aligned address to demonstrate HardFault (rust-embedded/book#374) ## rust-lang/nomicon 1 commits in 6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9..14649f15d232d509478206ee9ed5105641aa60d0 2024-08-14 14:49:09 UTC to 2024-08-14 14:49:09 UTC - CI: Switch to merge queue (rust-lang/nomicon#459) ## rust-lang/reference 14 commits in 62cd0df95061ba0ac886333f5cd7f3012f149da1..0668397076da350c404dadcf07b6cbc433ad3743 2024-08-11 21:06:12 +0000 to 2024-08-27 21:47:20 +0000 - Update enum.md (rust-lang/reference#1354) - Be consistent about how "Edition differences" is capitalized (rust-lang/reference#1586) - Sync denied lints with upstream (rust-lang/reference#1589) - const_eval: update for const-fn float stabilization (rust-lang/reference#1566) - Add spec identifier syntax to destructors.md (rust-lang/reference#1571) - Say that `pub(in path)` can't depend on `use` statements (rust-lang/reference#1559) - bytes inside implicitly const-promoted expressions are immutable (rust-lang/reference#1554) - Tweak `repr(transparent)` to mention requiring *at most* one non-1-ZST (rust-lang/reference#1568) - operator expressions: add &raw (rust-lang/reference#1567) - Rewrite the automatic std link translation, and switch to automatic links (rust-lang/reference#1578) - Add some basic docs for unsafe attrs (rust-lang/reference#1539) - don't capitalize Undefined Behavior (rust-lang/reference#1575) - add the `const` operand to docs for inline assembly (rust-lang/reference#1556) - Typo: 'a' to 'an' in type-coercions.md (rust-lang/reference#1572) ## rust-lang/rust-by-example 1 commits in 8f94061936e492159f4f6c09c0f917a7521893ff..859786c5bc99301bbc22fc631a5c2b341860da08 2024-08-26 10:30:48 UTC to 2024-08-26 10:30:48 UTC - Update primitives.md with examples (rust-lang/rust-by-example#1878) ## rust-lang/rustc-dev-guide 7 commits in 43d8378..fa928a6 2024-08-26 14:46:50 UTC to 2024-08-12 21:07:49 UTC - Fix x.py reference (rust-lang/rustc-dev-guide#2049) - Update `stabilization_guide.md` (rust-lang/rustc-dev-guide#2034) - Explain the internal `#[rustc_*]` TEST attributes used for debugging and inside tests (rust-lang/rustc-dev-guide#2046) - missing char (rust-lang/rustc-dev-guide#2047) - Replace direct http links to rustc-dev-guide.rust-lang.org (rust-lang/rustc-dev-guide#2044) - Update index.html, 39. The MIR: fix typo (rust-lang/rustc-dev-guide#2043) - Update LLVM docs (rust-lang/rustc-dev-guide#2039)
Update books ## rust-lang/book 4 commits in 04bc1396bb857f35b5dda1d773c9571e1f253304..e7d217be2a75ef1753f0988d6ccaba4d7e376259 2024-08-14 01:19:47 UTC to 2024-08-13 16:51:00 UTC - Backport/forward port ch12 (rust-lang/book#4008) - Found some more things to fix in ch7; I forgot to update the snapshot (rust-lang/book#4007) - Remove redundant sentence. Send to nostarch (rust-lang/book#4006) - Fix: typo (rust-lang/book#4003) ## rust-lang/edition-guide 5 commits in aeeb287d41a0332c210da122bea8e0e91844ab3e..eeba2cb9c37ab74118a4fb5e5233f7397e4a91f8 2024-08-19 23:28:06 UTC to 2024-08-15 15:12:33 UTC - 2024: Add rustdoc combined doctests (rust-lang/edition-guide#320) - Update for unsafe attributes stabilization (rust-lang/edition-guide#319) - 2024: Add macro-fragment-specifiers. (rust-lang/edition-guide#312) - Fix deprecated_safe_2024 link (rust-lang/edition-guide#317) - Add 2024 unsafe functions (rust-lang/edition-guide#304) ## rust-embedded/book 1 commits in 019f3928d8b939ec71b63722dcc2e46330156441..ff5d61d56f11e1986bfa9652c6aff7731576c37d 2024-08-20 07:26:19 UTC to 2024-08-20 07:26:19 UTC - Use aligned address to demonstrate HardFault (rust-embedded/book#374) ## rust-lang/nomicon 1 commits in 6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9..14649f15d232d509478206ee9ed5105641aa60d0 2024-08-14 14:49:09 UTC to 2024-08-14 14:49:09 UTC - CI: Switch to merge queue (rust-lang/nomicon#459) ## rust-lang/reference 14 commits in 62cd0df95061ba0ac886333f5cd7f3012f149da1..0668397076da350c404dadcf07b6cbc433ad3743 2024-08-11 21:06:12 +0000 to 2024-08-27 21:47:20 +0000 - Update enum.md (rust-lang/reference#1354) - Be consistent about how "Edition differences" is capitalized (rust-lang/reference#1586) - Sync denied lints with upstream (rust-lang/reference#1589) - const_eval: update for const-fn float stabilization (rust-lang/reference#1566) - Add spec identifier syntax to destructors.md (rust-lang/reference#1571) - Say that `pub(in path)` can't depend on `use` statements (rust-lang/reference#1559) - bytes inside implicitly const-promoted expressions are immutable (rust-lang/reference#1554) - Tweak `repr(transparent)` to mention requiring *at most* one non-1-ZST (rust-lang/reference#1568) - operator expressions: add &raw (rust-lang/reference#1567) - Rewrite the automatic std link translation, and switch to automatic links (rust-lang/reference#1578) - Add some basic docs for unsafe attrs (rust-lang/reference#1539) - don't capitalize Undefined Behavior (rust-lang/reference#1575) - add the `const` operand to docs for inline assembly (rust-lang/reference#1556) - Typo: 'a' to 'an' in type-coercions.md (rust-lang/reference#1572) ## rust-lang/rust-by-example 1 commits in 8f94061936e492159f4f6c09c0f917a7521893ff..859786c5bc99301bbc22fc631a5c2b341860da08 2024-08-26 10:30:48 UTC to 2024-08-26 10:30:48 UTC - Update primitives.md with examples (rust-lang/rust-by-example#1878) ## rust-lang/rustc-dev-guide 7 commits in 43d83780db545a1ed6d45773312fc578987e3968..fa928a6d19e1666d8d811dfe3fd35cdad3b4e459 2024-08-26 14:46:50 UTC to 2024-08-12 21:07:49 UTC - Fix x.py reference (rust-lang/rustc-dev-guide#2049) - Update `stabilization_guide.md` (rust-lang/rustc-dev-guide#2034) - Explain the internal `#[rustc_*]` TEST attributes used for debugging and inside tests (rust-lang/rustc-dev-guide#2046) - missing char (rust-lang/rustc-dev-guide#2047) - Replace direct http links to rustc-dev-guide.rust-lang.org (rust-lang/rustc-dev-guide#2044) - Update index.html, 39. The MIR: fix typo (rust-lang/rustc-dev-guide#2043) - Update LLVM docs (rust-lang/rustc-dev-guide#2039)
Tracking issue: rust-lang/rust#124853