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://github.com/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://github.com/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://github.com/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://github.com/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>),