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

‎compiler/rustc_borrowck/src/universal_regions.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -187,12 +187,12 @@ pub enum RegionClassification {
187187
///
188188
/// Consider this example:
189189
///
190-
/// ```
190+
/// ```ignore (pseudo-rust)
191191
/// fn foo<'a, 'b>(a: &'a u32, b: &'b u32, c: &'static u32) {
192192
/// let closure = for<'x> |x: &'x u32| { .. };
193-
/// ^^^^^^^ pretend this were legal syntax
194-
/// for declaring a late-bound region in
195-
/// a closure signature
193+
/// // ^^^^^^^ pretend this were legal syntax
194+
/// // for declaring a late-bound region in
195+
/// // a closure signature
196196
/// }
197197
/// ```
198198
///

‎compiler/rustc_builtin_macros/src/deriving/encodable.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
//!
66
//! For example, a type like:
77
//!
8-
//! ```
8+
//! ```ignore (old code)
99
//! #[derive(RustcEncodable, RustcDecodable)]
1010
//! struct Node { id: usize }
1111
//! ```
1212
//!
1313
//! would generate two implementations like:
1414
//!
15-
//! ```
15+
//! ```ignore (old code)
1616
//! # struct Node { id: usize }
1717
//! impl<S: Encoder<E>, E> Encodable<S, E> for Node {
1818
//! fn encode(&self, s: &mut S) -> Result<(), E> {
@@ -40,7 +40,7 @@
4040
//! Other interesting scenarios are when the item has type parameters or
4141
//! references other non-built-in types. A type definition like:
4242
//!
43-
//! ```
43+
//! ```ignore (old code)
4444
//! # #[derive(RustcEncodable, RustcDecodable)]
4545
//! # struct Span;
4646
//! #[derive(RustcEncodable, RustcDecodable)]
@@ -49,7 +49,7 @@
4949
//!
5050
//! would yield functions like:
5151
//!
52-
//! ```
52+
//! ```ignore (old code)
5353
//! # #[derive(RustcEncodable, RustcDecodable)]
5454
//! # struct Span;
5555
//! # struct Spanned<T> { node: T, span: Span }

‎compiler/rustc_builtin_macros/src/deriving/generic/mod.rs

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1006,9 +1006,11 @@ impl<'a> MethodDef<'a> {
10061006
/// }
10071007
/// }
10081008
/// }
1009-
///
1010-
/// // or if A is repr(packed) - note fields are matched by-value
1011-
/// // instead of by-reference.
1009+
/// ```
1010+
/// or if A is repr(packed) - note fields are matched by-value
1011+
/// instead of by-reference.
1012+
/// ```
1013+
/// # struct A { x: i32, y: i32 }
10121014
/// impl PartialEq for A {
10131015
/// fn eq(&self, other: &A) -> bool {
10141016
/// match *self {
@@ -1126,14 +1128,15 @@ impl<'a> MethodDef<'a> {
11261128
/// // is equivalent to
11271129
///
11281130
/// impl PartialEq for A {
1129-
/// fn eq(&self, other: &A) -> ::bool {
1131+
/// fn eq(&self, other: &A) -> bool {
1132+
/// use A::*;
11301133
/// match (&*self, &*other) {
11311134
/// (&A1, &A1) => true,
11321135
/// (&A2(ref self_0),
11331136
/// &A2(ref __arg_1_0)) => (*self_0).eq(&(*__arg_1_0)),
11341137
/// _ => {
1135-
/// let __self_vi = match *self { A1(..) => 0, A2(..) => 1 };
1136-
/// let __arg_1_vi = match *other { A1(..) => 0, A2(..) => 1 };
1138+
/// let __self_vi = match *self { A1 => 0, A2(..) => 1 };
1139+
/// let __arg_1_vi = match *other { A1 => 0, A2(..) => 1 };
11371140
/// false
11381141
/// }
11391142
/// }

‎compiler/rustc_builtin_macros/src/test_harness.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,7 @@ fn generate_test_harness(
249249
///
250250
/// By default this expands to
251251
///
252-
/// ```
252+
/// ```ignore UNSOLVED (I think I still need guidance for this one. Is it correct? Do we try to make it run? How do we nicely fill it out?)
253253
/// #[rustc_main]
254254
/// pub fn main() {
255255
/// extern crate test;

‎compiler/rustc_codegen_llvm/src/back/lto.rs

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -394,15 +394,15 @@ impl Drop for Linker<'_> {
394394
///
395395
/// At a high level Thin LTO looks like:
396396
///
397-
/// 1. Prepare a "summary" of each LLVM module in question which describes
398-
/// the values inside, cost of the values, etc.
399-
/// 2. Merge the summaries of all modules in question into one "index"
400-
/// 3. Perform some global analysis on this index
401-
/// 4. For each module, use the index and analysis calculated previously to
402-
/// perform local transformations on the module, for example inlining
403-
/// small functions from other modules.
404-
/// 5. Run thin-specific optimization passes over each module, and then code
405-
/// generate everything at the end.
397+
/// 1. Prepare a "summary" of each LLVM module in question which describes
398+
/// the values inside, cost of the values, etc.
399+
/// 2. Merge the summaries of all modules in question into one "index"
400+
/// 3. Perform some global analysis on this index
401+
/// 4. For each module, use the index and analysis calculated previously to
402+
/// perform local transformations on the module, for example inlining
403+
/// small functions from other modules.
404+
/// 5. Run thin-specific optimization passes over each module, and then code
405+
/// generate everything at the end.
406406
///
407407
/// The summary for each module is intended to be quite cheap, and the global
408408
/// index is relatively quite cheap to create as well. As a result, the goal of

‎compiler/rustc_codegen_llvm/src/debuginfo/doc.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ The module is thus driven from an outside client with functions like
2727
Internally the module will try to reuse already created metadata by
2828
utilizing a cache. The way to get a shared metadata node when needed is
2929
thus to just call the corresponding function in this module:
30-
31-
let file_metadata = file_metadata(cx, file);
32-
30+
```ignore (illustrative)
31+
let file_metadata = file_metadata(cx, file);
32+
```
3333
The function will take care of probing the cache for an existing node for
3434
that exact file path.
3535

@@ -63,7 +63,7 @@ struct List {
6363

6464
will generate the following callstack with a naive DFS algorithm:
6565

66-
```
66+
```ignore (illustrative)
6767
describe(t = List)
6868
describe(t = i32)
6969
describe(t = Option<Box<List>>)

‎compiler/rustc_data_structures/src/frozen.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
//! `computed` does not change accidentally (e.g. somebody might accidentally call
2424
//! `foo.computed.mutate()`). This is what `Frozen` is for. We can do the following:
2525
//!
26-
//! ```rust
26+
//! ```
27+
//! # struct Bar {}
2728
//! use rustc_data_structures::frozen::Frozen;
2829
//!
2930
//! struct Foo {

‎compiler/rustc_data_structures/src/obligation_forest/mod.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ impl<O> Node<O> {
202202
/// with this node.
203203
///
204204
/// The non-`Error` state transitions are as follows.
205-
/// ```
205+
/// ```text
206206
/// (Pre-creation)
207207
/// |
208208
/// | register_obligation_at() (called by process_obligations() and

0 commit comments

Comments
 (0)