Skip to content

Commit 574830f

Browse files
borsbors
committed
Auto merge of #96094 - Elliot-Roberts:fix_doctests, r=compiler-errors
Begin fixing all the broken doctests in `compiler/` Begins to fix #95994. All of them pass now but 24 of them I've marked with `ignore HELP (<explanation>)` (asking for help) as I'm unsure how to get them to work / if we should leave them as they are. There are also a few that I marked `ignore` that could maybe be made to work but seem less important. Each `ignore` has a rough "reason" for ignoring after it parentheses, with - `(pseudo-rust)` meaning "mostly rust-like but contains foreign syntax" - `(illustrative)` a somewhat catchall for either a fragment of rust that doesn't stand on its own (like a lone type), or abbreviated rust with ellipses and undeclared types that would get too cluttered if made compile-worthy. - `(not-rust)` stuff that isn't rust but benefits from the syntax highlighting, like MIR. - `(internal)` uses `rustc_*` code which would be difficult to make work with the testing setup. Those reason notes are a bit inconsistently applied and messy though. If that's important I can go through them again and try a more principled approach. When I run `rg '```ignore \(' .` on the repo, there look to be lots of different conventions other people have used for this sort of thing. I could try unifying them all if that would be helpful. I'm not sure if there was a better existing way to do this but I wrote my own script to help me run all the doctests and wade through the output. If that would be useful to anyone else, I put it here: https://github.com/Elliot-Roberts/rust_doctest_fixing_tool
2 parents 36aa7c1 + 647d0b6 commit 574830f

File tree

116 files changed

+668
-609
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+668
-609
lines changed

‎compiler/rustc_ast/src/ast.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -573,7 +573,7 @@ pub struct Block {
573573
pub span: Span,
574574
pub tokens: Option<LazyTokenStream>,
575575
/// The following *isn't* a parse error, but will cause multiple errors in following stages.
576-
/// ```
576+
/// ```compile_fail
577577
/// let x = {
578578
/// foo: var
579579
/// };

‎compiler/rustc_ast_lowering/src/expr.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
616616
}
617617

618618
/// Desugar `<expr>.await` into:
619-
/// ```rust
619+
/// ```ignore (pseudo-rust)
620620
/// match ::std::future::IntoFuture::into_future(<expr>) {
621621
/// mut __awaitee => loop {
622622
/// match unsafe { ::std::future::Future::poll(
@@ -1363,7 +1363,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
13631363
}
13641364

13651365
/// Desugar `ExprForLoop` from: `[opt_ident]: for <pat> in <head> <body>` into:
1366-
/// ```rust
1366+
/// ```ignore (pseudo-rust)
13671367
/// {
13681368
/// let result = match IntoIterator::into_iter(<head>) {
13691369
/// mut iter => {
@@ -1474,7 +1474,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
14741474
}
14751475

14761476
/// Desugar `ExprKind::Try` from: `<expr>?` into:
1477-
/// ```rust
1477+
/// ```ignore (pseudo-rust)
14781478
/// match Try::branch(<expr>) {
14791479
/// ControlFlow::Continue(val) => #[allow(unreachable_code)] val,,
14801480
/// ControlFlow::Break(residual) =>

‎compiler/rustc_ast_lowering/src/lib.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -920,7 +920,7 @@ impl<'a, 'hir> LoweringContext<'a, 'hir> {
920920

921921
/// Given an associated type constraint like one of these:
922922
///
923-
/// ```
923+
/// ```ignore (illustrative)
924924
/// T: Iterator<Item: Debug>
925925
/// ^^^^^^^^^^^
926926
/// T: Iterator<Item = Debug>

‎compiler/rustc_ast_pretty/src/pp.rs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,20 +68,20 @@
6868
//! will be made to flow subsequent breaks together onto lines. Inconsistent
6969
//! is the opposite. Inconsistent breaking example would be, say:
7070
//!
71-
//! ```
71+
//! ```ignore (illustrative)
7272
//! foo(hello, there, good, friends)
7373
//! ```
7474
//!
7575
//! breaking inconsistently to become
7676
//!
77-
//! ```
77+
//! ```ignore (illustrative)
7878
//! foo(hello, there,
7979
//! good, friends);
8080
//! ```
8181
//!
8282
//! whereas a consistent breaking would yield:
8383
//!
84-
//! ```
84+
//! ```ignore (illustrative)
8585
//! foo(hello,
8686
//! there,
8787
//! good,
@@ -153,14 +153,14 @@ enum IndentStyle {
153153
/// Vertically aligned under whatever column this block begins at.
154154
///
155155
/// fn demo(arg1: usize,
156-
/// arg2: usize);
156+
/// arg2: usize) {}
157157
Visual,
158158
/// Indented relative to the indentation level of the previous line.
159159
///
160160
/// fn demo(
161161
/// arg1: usize,
162162
/// arg2: usize,
163-
/// );
163+
/// ) {}
164164
Block { offset: isize },
165165
}
166166

‎compiler/rustc_borrowck/src/diagnostics/conflict_errors.rs

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -896,20 +896,23 @@ impl<'cx, 'tcx> MirBorrowckCtxt<'cx, 'tcx> {
896896
///
897897
/// In the simplest case, where there are no unions involved, if a mutable borrow of `x` is
898898
/// attempted while a shared borrow is live, then this function will return:
899-
///
900-
/// ("x", "", "")
901-
///
899+
/// ```
900+
/// ("x", "", "")
901+
/// # ;
902+
/// ```
902903
/// In the simple union case, if a mutable borrow of a union field `x.z` is attempted while
903904
/// a shared borrow of another field `x.y`, then this function will return:
904-
///
905-
/// ("x", "x.z", "x.y")
906-
///
905+
/// ```
906+
/// ("x", "x.z", "x.y")
907+
/// # ;
908+
/// ```
907909
/// In the more complex union case, where the union is a field of a struct, then if a mutable
908910
/// borrow of a union field in a struct `x.u.z` is attempted while a shared borrow of
909911
/// another field `x.u.y`, then this function will return:
910-
///
911-
/// ("x.u", "x.u.z", "x.u.y")
912-
///
912+
/// ```
913+
/// ("x.u", "x.u.z", "x.u.y")
914+
/// # ;
915+
/// ```
913916
/// This is used when creating error messages like below:
914917
///
915918
/// ```text

‎compiler/rustc_borrowck/src/diagnostics/region_errors.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,7 @@ impl<'a, 'tcx> MirBorrowckCtxt<'a, 'tcx> {
259259
/// Report an error because the universal region `fr` was required to outlive
260260
/// `outlived_fr` but it is not known to do so. For example:
261261
///
262-
/// ```
262+
/// ```compile_fail,E0312
263263
/// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
264264
/// ```
265265
///

‎compiler/rustc_borrowck/src/diagnostics/region_name.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ impl<'tcx> MirBorrowckCtxt<'_, 'tcx> {
210210
/// Suppose we are trying to give a name to the lifetime of the
211211
/// reference `x`:
212212
///
213-
/// ```
213+
/// ```ignore (pseudo-rust)
214214
/// fn foo(x: &u32) { .. }
215215
/// ```
216216
///
@@ -746,7 +746,7 @@ impl<'tcx> MirBorrowckCtxt<'_, 'tcx> {
746746
/// e.g. given the function:
747747
///
748748
/// ```
749-
/// async fn foo() -> i32 {}
749+
/// async fn foo() -> i32 { 2 }
750750
/// ```
751751
///
752752
/// this function, given the lowered return type of `foo`, an [`OpaqueDef`] that implements `Future<Output=i32>`,

‎compiler/rustc_borrowck/src/member_constraints.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ where
169169
/// Returns the "choice regions" for a given member
170170
/// constraint. This is the `R1..Rn` from a constraint like:
171171
///
172-
/// ```
172+
/// ```text
173173
/// R0 member of [R1..Rn]
174174
/// ```
175175
crate fn choice_regions(&self, pci: NllMemberConstraintIndex) -> &[ty::RegionVid] {
@@ -195,14 +195,14 @@ where
195195
///
196196
/// Before:
197197
///
198-
/// ```
198+
/// ```text
199199
/// target_list: A -> B -> C -> (None)
200200
/// source_list: D -> E -> F -> (None)
201201
/// ```
202202
///
203203
/// After:
204204
///
205-
/// ```
205+
/// ```text
206206
/// target_list: A -> B -> C -> D -> E -> F -> (None)
207207
/// ```
208208
fn append_list(

‎compiler/rustc_borrowck/src/region_infer/mod.rs

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -436,14 +436,14 @@ impl<'tcx> RegionInferenceContext<'tcx> {
436436
/// minimum values.
437437
///
438438
/// For example:
439-
///
440-
/// fn foo<'a, 'b>(..) where 'a: 'b
441-
///
439+
/// ```
440+
/// fn foo<'a, 'b>( /* ... */ ) where 'a: 'b { /* ... */ }
441+
/// ```
442442
/// would initialize two variables like so:
443-
///
444-
/// R0 = { CFG, R0 } // 'a
445-
/// R1 = { CFG, R0, R1 } // 'b
446-
///
443+
/// ```ignore (illustrative)
444+
/// R0 = { CFG, R0 } // 'a
445+
/// R1 = { CFG, R0, R1 } // 'b
446+
/// ```
447447
/// Here, R0 represents `'a`, and it contains (a) the entire CFG
448448
/// and (b) any universally quantified regions that it outlives,
449449
/// which in this case is just itself. R1 (`'b`) in contrast also
@@ -1310,9 +1310,9 @@ impl<'tcx> RegionInferenceContext<'tcx> {
13101310
/// whether any of the constraints were too strong. In particular,
13111311
/// we want to check for a case where a universally quantified
13121312
/// region exceeded its bounds. Consider:
1313-
///
1314-
/// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
1315-
///
1313+
/// ```compile_fail,E0312
1314+
/// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
1315+
/// ```
13161316
/// In this case, returning `x` requires `&'a u32 <: &'b u32`
13171317
/// and hence we establish (transitively) a constraint that
13181318
/// `'a: 'b`. The `propagate_constraints` code above will
@@ -1366,9 +1366,9 @@ impl<'tcx> RegionInferenceContext<'tcx> {
13661366
/// <https://smallcultfollowing.com/babysteps/blog/2019/01/17/polonius-and-region-errors/>
13671367
///
13681368
/// In the canonical example
1369-
///
1370-
/// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
1371-
///
1369+
/// ```compile_fail,E0312
1370+
/// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
1371+
/// ```
13721372
/// returning `x` requires `&'a u32 <: &'b u32` and hence we establish (transitively) a
13731373
/// constraint that `'a: 'b`. It is an error that we have no evidence that this
13741374
/// constraint holds.

‎compiler/rustc_borrowck/src/type_check/mod.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -971,7 +971,7 @@ pub enum Locations {
971971
/// things like the type of the return slot. Consider this
972972
/// example:
973973
///
974-
/// ```
974+
/// ```compile_fail,E0515
975975
/// fn foo<'a>(x: &'a u32) -> &'a u32 {
976976
/// let y = 22;
977977
/// return &y; // error

0 commit comments

Comments
 (0)