Add compiler docs testing to CI.

src/ci/docker/x86_64-gnu/Dockerfile

@@ -16,5 +16,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY scripts/sccache.sh /scripts/
 RUN sh /scripts/sccache.sh
 
-ENV RUST_CONFIGURE_ARGS --build=x86_64-unknown-linux-gnu --enable-sanitizers --enable-profiler
+ENV RUST_CONFIGURE_ARGS \
+ --build=x86_64-unknown-linux-gnu \
+ --enable-sanitizers \
+ --enable-profiler \
+ --enable-compiler-docs
 ENV SCRIPT python2.7 ../x.py test

src/libarena/lib.rs

@@ -148,10 +148,11 @@ impl<T> TypedArena<T> {
  }
  }
 
- /// Allocates a slice of objects that are copy into the `TypedArena`, returning a mutable
+ /// Allocates a slice of objects that are copied into the `TypedArena`, returning a mutable
  /// reference to it. Will panic if passed a zero-sized types.
  ///
  /// Panics:
+ ///
  /// - Zero-sized types
  /// - Zero-length slices
  #[inline]
@@ -369,6 +370,7 @@ impl DroplessArena {
  /// reference to it. Will panic if passed a zero-sized type.
  ///
  /// Panics:
+ ///
  /// - Zero-sized types
  /// - Zero-length slices
  #[inline]

src/libgraphviz/lib.rs

@@ -306,7 +306,7 @@ pub enum LabelText<'a> {
  LabelStr(Cow<'a, str>),
 
  /// This kind of label uses the graphviz label escString type:
- /// http://www.graphviz.org/content/attrs#kescString
+ /// <http://www.graphviz.org/content/attrs#kescString>
  ///
  /// Occurrences of backslashes (`\`) are not escaped; instead they
  /// are interpreted as initiating an escString escape sequence.
@@ -326,7 +326,7 @@ pub enum LabelText<'a> {
 }
 
 /// The style for a node or edge.
-/// See http://www.graphviz.org/doc/info/attrs.html#k:style for descriptions.
+/// See <http://www.graphviz.org/doc/info/attrs.html#k:style> for descriptions.
 /// Note that some of these are not valid for edges.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub enum Style {

src/librustc/Cargo.toml

@@ -54,4 +54,4 @@ byteorder = { version = "1.1", features = ["i128"]}
 # tl;dr; this is not needed to get `rustc` to compile, but if you remove it then
 # later crate stop compiling. If you can remove this and everything
 # compiles, then please feel free to do so!
-flate2 = "0.2"
+flate2 = "1.0"

src/librustc/dep_graph/dep_tracking_map.rs

@@ -56,7 +56,7 @@ impl<M: DepTrackingMapConfig> MemoizationMap for RefCell<DepTrackingMap<M>> {
  /// map; and `CurrentTask` represents the current task when
  /// `memoize` is invoked.
  ///
- /// **Important:* when `op` is invoked, the current task will be
+ /// **Important:** when `op` is invoked, the current task will be
  /// switched to `Map(key)`. Therefore, if `op` makes use of any
  /// HIR nodes or shared state accessed through its closure
  /// environment, it must explicitly register a read of that

src/librustc/dep_graph/graph.rs

@@ -158,8 +158,8 @@ impl DepGraph {
  /// what state they have access to. In particular, we want to
  /// prevent implicit 'leaks' of tracked state into the task (which
  /// could then be read without generating correct edges in the
- /// dep-graph -- see the [README] for more details on the
- /// dep-graph). To this end, the task function gets exactly two
+ /// dep-graph -- see the module-level [README] for more details on
+ /// the dep-graph). To this end, the task function gets exactly two
  /// pieces of state: the context `cx` and an argument `arg`. Both
  /// of these bits of state must be of some type that implements
  /// `DepGraphSafe` and hence does not leak.
@@ -178,7 +178,7 @@ impl DepGraph {
  /// - If you need 3+ arguments, use a tuple for the
  /// `arg` parameter.
  ///
- /// [README]: README.md
+ /// [README]: https:/rust-lang/rust/blob/master/src/librustc/dep_graph/README.md
  pub fn with_task<C, A, R, HCX>(&self,
  key: DepNode,
  cx: C,

src/librustc/hir/def.rs

@@ -71,13 +71,16 @@ pub enum Def {
 /// `base_def` is definition of resolved part of the
 /// path, `unresolved_segments` is the number of unresolved
 /// segments.
-/// module::Type::AssocX::AssocY::MethodOrAssocType
-/// ^~~~~~~~~~~~ ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-/// base_def unresolved_segments = 3
 ///
-/// <T as Trait>::AssocX::AssocY::MethodOrAssocType
-/// ^~~~~~~~~~~~~~ ^~~~~~~~~~~~~~~~~~~~~~~~~
-/// base_def unresolved_segments = 2
+/// ```text
+/// module::Type::AssocX::AssocY::MethodOrAssocType
+/// ^~~~~~~~~~~~ ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+/// base_def unresolved_segments = 3
+///
+/// <T as Trait>::AssocX::AssocY::MethodOrAssocType
+/// ^~~~~~~~~~~~~~ ^~~~~~~~~~~~~~~~~~~~~~~~~
+/// base_def unresolved_segments = 2
+/// ```
 #[derive(Copy, Clone, Debug)]
 pub struct PathResolution {
  base_def: Def,

src/librustc/hir/map/blocks.rs

@@ -33,6 +33,7 @@ use syntax_pos::Span;
 /// and a body (as well as a NodeId, a span, etc).
 ///
 /// More specifically, it is one of either:
+///
 /// - A function item,
 /// - A closure expr (i.e. an ExprClosure), or
 /// - The default implementation for a trait method.

src/librustc/hir/mod.rs

@@ -588,7 +588,9 @@ pub type CrateConfig = HirVec<P<MetaItem>>;
 /// The top-level data structure that stores the entire contents of
 /// the crate currently being compiled.
 ///
-/// For more details, see [the module-level README](README.md).
+/// For more details, see the module-level [README].
+///
+/// [README]: https:/rust-lang/rust/blob/master/src/librustc/hir/README.md.
 #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)]
 pub struct Crate {
  pub module: Mod,

src/librustc/infer/anon_types/mod.rs

@@ -147,21 +147,25 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  /// Let's work through an example to explain how it works. Assume
  /// the current function is as follows:
  ///
- /// fn foo<'a, 'b>(..) -> (impl Bar<'a>, impl Bar<'b>)
+ /// ```text
+ /// fn foo<'a, 'b>(..) -> (impl Bar<'a>, impl Bar<'b>)
+ /// ```
  ///
  /// Here, we have two `impl Trait` types whose values are being
  /// inferred (the `impl Bar<'a>` and the `impl
  /// Bar<'b>`). Conceptually, this is sugar for a setup where we
  /// define underlying abstract types (`Foo1`, `Foo2`) and then, in
  /// the return type of `foo`, we *reference* those definitions:
  ///
- /// abstract type Foo1<'x>: Bar<'x>;
- /// abstract type Foo2<'x>: Bar<'x>;
- /// fn foo<'a, 'b>(..) -> (Foo1<'a>, Foo2<'b>) { .. }
- /// // ^^^^ ^^
- /// // | |
- /// // | substs
- /// // def_id
+ /// ```text
+ /// abstract type Foo1<'x>: Bar<'x>;
+ /// abstract type Foo2<'x>: Bar<'x>;
+ /// fn foo<'a, 'b>(..) -> (Foo1<'a>, Foo2<'b>) { .. }
+ /// // ^^^^ ^^
+ /// // | |
+ /// // | substs
+ /// // def_id
+ /// ```
  ///
  /// As indicating in the comments above, each of those references
  /// is (in the compiler) basically a substitution (`substs`)
@@ -175,8 +179,10 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  /// `Foo2`. That is, this gives rise to higher-order (pattern) unification
  /// constraints like:
  ///
- /// for<'a> (Foo1<'a> = C1)
- /// for<'b> (Foo1<'b> = C2)
+ /// ```text
+ /// for<'a> (Foo1<'a> = C1)
+ /// for<'b> (Foo1<'b> = C2)
+ /// ```
  ///
  /// For these equation to be satisfiable, the types `C1` and `C2`
  /// can only refer to a limited set of regions. For example, `C1`
@@ -189,15 +195,19 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  /// regions. In fact, it is fairly likely that they do! Consider
  /// this possible definition of `foo`:
  ///
- /// fn foo<'a, 'b>(x: &'a i32, y: &'b i32) -> (impl Bar<'a>, impl Bar<'b>) {
+ /// ```text
+ /// fn foo<'a, 'b>(x: &'a i32, y: &'b i32) -> (impl Bar<'a>, impl Bar<'b>) {
  /// (&*x, &*y)
  /// }
+ /// ```
  ///
  /// Here, the values for the concrete types of the two impl
  /// traits will include inference variables:
  ///
- /// &'0 i32
- /// &'1 i32
+ /// ```text
+ /// &'0 i32
+ /// &'1 i32
+ /// ```
  ///
  /// Ordinarily, the subtyping rules would ensure that these are
  /// sufficiently large. But since `impl Bar<'a>` isn't a specific
@@ -207,7 +217,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  /// inferred type are regions that could validly appear.
  ///
  /// This is actually a bit of a tricky constraint in general. We
- /// want to say that each variable (e.g., `'0``) can only take on
+ /// want to say that each variable (e.g., `'0`) can only take on
  /// values that were supplied as arguments to the abstract type
  /// (e.g., `'a` for `Foo1<'a>`) or `'static`, which is always in
  /// scope. We don't have a constraint quite of this kind in the current
@@ -225,7 +235,9 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  ///
  /// In some cases, there is no minimum. Consider this example:
  ///
- /// fn baz<'a, 'b>() -> impl Trait<'a, 'b> { ... }
+ /// ```text
+ /// fn baz<'a, 'b>() -> impl Trait<'a, 'b> { ... }
+ /// ```
  ///
  /// Here we would report an error, because `'a` and `'b` have no
  /// relation to one another.
@@ -245,8 +257,10 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> {
  /// which is the current function. It also means that we can
  /// take "implied bounds" into account in some cases:
  ///
- /// trait SomeTrait<'a, 'b> { }
- /// fn foo<'a, 'b>(_: &'a &'b u32) -> impl SomeTrait<'a, 'b> { .. }
+ /// ```text
+ /// trait SomeTrait<'a, 'b> { }
+ /// fn foo<'a, 'b>(_: &'a &'b u32) -> impl SomeTrait<'a, 'b> { .. }
+ /// ```
  ///
  /// Here, the fact that `'b: 'a` is known only because of the
  /// implied bounds from the `&'a &'b u32` parameter, and is not

src/librustc/middle/region.rs

@@ -53,9 +53,9 @@ use rustc_data_structures::stable_hasher::{HashStable, StableHasher,
 /// expression for the indexed statement, until the end of the block.
 ///
 /// So: the following code can be broken down into the scopes beneath:
-/// ```
+///
+/// ```text
 /// let a = f().g( 'b: { let x = d(); let y = d(); x.h(y) } ) ;
-/// ```
 ///
 /// +-+ (D12.)
 /// +-+ (D11.)
@@ -82,6 +82,7 @@ use rustc_data_structures::stable_hasher::{HashStable, StableHasher,
 /// (R10.): Remainder scope for block `'b:`, stmt 1 (let y = ...).
 /// (D11.): DestructionScope for temporaries and bindings from block `'b:`.
 /// (D12.): DestructionScope for temporaries created during M1 (e.g. f()).
+/// ```
 ///
 /// Note that while the above picture shows the destruction scopes
 /// as following their corresponding node scopes, in the internal

src/librustc/mir/mod.rs

@@ -8,7 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! MIR datatypes and passes. See [the README](README.md) for details.
+//! MIR datatypes and passes. See the module-level [README] for details.
+//!
+//! [README]: https:/rust-lang/rust/blob/master/src/librustc/mir/README.md
 
 use graphviz::IntoCow;
 use middle::const_val::ConstVal;
@@ -495,6 +497,7 @@ pub struct LocalDecl<'tcx> {
  ///
  /// That's it, if we have a let-statement like the one in this
  /// function:
+ ///
  /// ```
  /// fn foo(x: &str) {
  /// #[allow(unused_mut)]
@@ -538,6 +541,7 @@ pub struct LocalDecl<'tcx> {
  ///
  /// The end result looks like this:
  ///
+ /// ```text
  /// ROOT SCOPE
  /// │{ argument x: &str }
  /// │
@@ -557,6 +561,7 @@ pub struct LocalDecl<'tcx> {
  /// │ │{ let x: u32 }
  /// │ │← x.source_info.scope
  /// │ │← `drop(x)` // this accesses `x: u32`
+ /// ```
  pub syntactic_scope: VisibilityScope,
 }
 

src/librustc/traits/select.rs

@@ -906,6 +906,7 @@ impl<'cx, 'gcx, 'tcx> SelectionContext<'cx, 'gcx, 'tcx> {
  /// For defaulted traits, we use a co-inductive strategy to solve, so
  /// that recursion is ok. This routine returns true if the top of the
  /// stack (`cycle[0]`):
+ ///
  /// - is a defaulted trait, and
  /// - it also appears in the backtrace at some position `X`; and,
  /// - all the predicates at positions `X..` between `X` an the top are

src/librustc/ty/adjustment.rs

@@ -22,38 +22,38 @@ use ty::subst::Substs;
 /// Here are some common scenarios:
 ///
 /// 1. The simplest cases are where a pointer is not adjusted fat vs thin.
-/// Here the pointer will be dereferenced N times (where a dereference can
-/// happen to raw or borrowed pointers or any smart pointer which implements
-/// Deref, including Box<_>). The types of dereferences is given by
-/// `autoderefs`. It can then be auto-referenced zero or one times, indicated
-/// by `autoref`, to either a raw or borrowed pointer. In these cases unsize is
-/// `false`.
+///  Here the pointer will be dereferenced N times (where a dereference can
+///  happen to raw or borrowed pointers or any smart pointer which implements
+///  Deref, including Box<_>). The types of dereferences is given by
+///  `autoderefs`. It can then be auto-referenced zero or one times, indicated
+///  by `autoref`, to either a raw or borrowed pointer. In these cases unsize is
+///  `false`.
 ///
 /// 2. A thin-to-fat coercion involves unsizing the underlying data. We start
-/// with a thin pointer, deref a number of times, unsize the underlying data,
-/// then autoref. The 'unsize' phase may change a fixed length array to a
-/// dynamically sized one, a concrete object to a trait object, or statically
-/// sized struct to a dynamically sized one. E.g., &[i32; 4] -> &[i32] is
-/// represented by:
+///  with a thin pointer, deref a number of times, unsize the underlying data,
+///  then autoref. The 'unsize' phase may change a fixed length array to a
+///  dynamically sized one, a concrete object to a trait object, or statically
+///  sized struct to a dynamically sized one. E.g., &[i32; 4] -> &[i32] is
+///  represented by:
 ///
-/// ```
-/// Deref(None) -> [i32; 4],
-/// Borrow(AutoBorrow::Ref) -> &[i32; 4],
-/// Unsize -> &[i32],
-/// ```
+///  ```
+///  Deref(None) -> [i32; 4],
+///  Borrow(AutoBorrow::Ref) -> &[i32; 4],
+///  Unsize -> &[i32],
+///  ```
 ///
-/// Note that for a struct, the 'deep' unsizing of the struct is not recorded.
-/// E.g., `struct Foo<T> { x: T }` we can coerce &Foo<[i32; 4]> to &Foo<[i32]>
-/// The autoderef and -ref are the same as in the above example, but the type
-/// stored in `unsize` is `Foo<[i32]>`, we don't store any further detail about
-/// the underlying conversions from `[i32; 4]` to `[i32]`.
+///  Note that for a struct, the 'deep' unsizing of the struct is not recorded.
+///  E.g., `struct Foo<T> { x: T }` we can coerce &Foo<[i32; 4]> to &Foo<[i32]>
+///  The autoderef and -ref are the same as in the above example, but the type
+///  stored in `unsize` is `Foo<[i32]>`, we don't store any further detail about
+///  the underlying conversions from `[i32; 4]` to `[i32]`.
 ///
 /// 3. Coercing a `Box<T>` to `Box<Trait>` is an interesting special case. In
-/// that case, we have the pointer we need coming in, so there are no
-/// autoderefs, and no autoref. Instead we just do the `Unsize` transformation.
-/// At some point, of course, `Box` should move out of the compiler, in which
-/// case this is analogous to transforming a struct. E.g., Box<[i32; 4]> ->
-/// Box<[i32]> is an `Adjust::Unsize` with the target `Box<[i32]>`.
+///  that case, we have the pointer we need coming in, so there are no
+///  autoderefs, and no autoref. Instead we just do the `Unsize` transformation.
+///  At some point, of course, `Box` should move out of the compiler, in which
+///  case this is analogous to transforming a struct. E.g., Box<[i32; 4]> ->
+///  Box<[i32]> is an `Adjust::Unsize` with the target `Box<[i32]>`.
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub struct Adjustment<'tcx> {
  pub kind: Adjust<'tcx>,

src/librustc/ty/context.rs

@@ -778,8 +778,10 @@ impl<'tcx> CommonTypes<'tcx> {
 
 /// The central data structure of the compiler. It stores references
 /// to the various **arenas** and also houses the results of the
-/// various **compiler queries** that have been performed. See [the
-/// README](README.md) for more deatils.
+/// various **compiler queries** that have been performed. See the
+/// module-level [README] for more details.
+///
+/// [README]: https:/rust-lang/rust/blob/master/src/librustc/ty/README.md
 #[derive(Copy, Clone)]
 pub struct TyCtxt<'a, 'gcx: 'a+'tcx, 'tcx: 'a> {
  gcx: &'a GlobalCtxt<'gcx>,

src/librustc/ty/instance.rs

@@ -28,7 +28,7 @@ pub enum InstanceDef<'tcx> {
  Item(DefId),
  Intrinsic(DefId),
 
- /// <fn() as FnTrait>::call_*
+ /// \<fn() as FnTrait>::call_*
  /// def-id is FnTrait::call_*
  FnPtrShim(DefId, Ty<'tcx>),