Fix docs for future pulldown migration

Author: MaloJaffre

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/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/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/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

@@ -497,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)]
@@ -540,6 +541,7 @@ pub struct LocalDecl<'tcx> {
     ///
     /// The end result looks like this:
     ///
+    /// ```text
     /// ROOT SCOPE
     ///  │{ argument x: &str }
     ///  │
@@ -559,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/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>),
 

src/librustc/ty/layout.rs

@@ -340,8 +340,8 @@ impl AddAssign for Size {
 
 /// Alignment of a type in bytes, both ABI-mandated and preferred.
 /// Each field is a power of two, giving the alignment a maximum
-/// value of 2^(2^8 - 1), which is limited by LLVM to a i32, with
-/// a maximum capacity of 2^31 - 1 or 2147483647.
+/// value of 2<sup>(2<sup>8</sup> - 1)</sup>, which is limited by LLVM to a i32, with
+/// a maximum capacity of 2<sup>31</sup> - 1 or 2147483647.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
 pub struct Align {
     abi: u8,
@@ -651,11 +651,13 @@ impl Scalar {
 }
 
 /// The first half of a fat pointer.
+///
 /// - For a trait object, this is the address of the box.
 /// - For a slice, this is the base address.
 pub const FAT_PTR_ADDR: usize = 0;
 
 /// The second half of a fat pointer.
+///
 /// - For a trait object, this is the address of the vtable.
 /// - For a slice, this is the length.
 pub const FAT_PTR_EXTRA: usize = 1;

src/librustc/ty/mod.rs

@@ -1098,8 +1098,8 @@ pub type PolySubtypePredicate<'tcx> = ty::Binder<SubtypePredicate<'tcx>>;
 /// In particular, form #1 is "desugared" to the combination of a
 /// normal trait predicate (`T : TraitRef<...>`) and one of these
 /// predicates. Form #2 is a broader form in that it also permits
-/// equality between arbitrary types. Processing an instance of Form
-/// #2 eventually yields one of these `ProjectionPredicate`
+/// equality between arbitrary types. Processing an instance of
+/// Form #2 eventually yields one of these `ProjectionPredicate`
 /// instances to normalize the LHS.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, RustcEncodable, RustcDecodable)]
 pub struct ProjectionPredicate<'tcx> {
@@ -1401,7 +1401,7 @@ bitflags! {
         /// fields/variants) and as such, whether downstream crates must match exhaustively on the
         /// fields/variants of this data type.
         ///
-        /// See RFC 2008 (https://github.com/rust-lang/rfcs/pull/2008).
+        /// See RFC 2008 (<https://github.com/rust-lang/rfcs/pull/2008>).
         const IS_NON_EXHAUSTIVE   = 1 << 5;
     }
 }

src/librustc/ty/sty.rs

@@ -673,6 +673,7 @@ impl<T> Binder<T> {
     /// accounting.
     ///
     /// Some examples where `skip_binder` is reasonable:
+    ///
     /// - extracting the def-id from a PolyTraitRef;
     /// - comparing the self type of a PolyTraitRef to see if it is equal to
     ///   a type parameter `X`, since the type `X`  does not reference any regions
@@ -992,8 +993,8 @@ pub type Region<'tcx> = &'tcx RegionKind;
 /// happen, you can use `leak_check`. This is more clearly explained
 /// by infer/higher_ranked/README.md.
 ///
-/// [1] http://smallcultfollowing.com/babysteps/blog/2013/10/29/intermingled-parameter-lists/
-/// [2] http://smallcultfollowing.com/babysteps/blog/2013/11/04/intermingled-parameter-lists/
+/// [1]: http://smallcultfollowing.com/babysteps/blog/2013/10/29/intermingled-parameter-lists/
+/// [2]: http://smallcultfollowing.com/babysteps/blog/2013/11/04/intermingled-parameter-lists/
 #[derive(Clone, PartialEq, Eq, Hash, Copy, RustcEncodable, RustcDecodable, PartialOrd, Ord)]
 pub enum RegionKind {
     // Region bound in a type or fn declaration which will be

src/librustc_apfloat/ieee.rs

@@ -65,11 +65,11 @@ pub trait Semantics: Sized {
     /// Number of bits in the significand. This includes the integer bit.
     const PRECISION: usize;
 
-    /// The largest E such that 2^E is representable; this matches the
+    /// The largest E such that 2<sup>E</sup> is representable; this matches the
     /// definition of IEEE 754.
     const MAX_EXP: ExpInt;
 
-    /// The smallest E such that 2^E is a normalized number; this
+    /// The smallest E such that 2<sup>E</sup> is a normalized number; this
     /// matches the definition of IEEE 754.
     const MIN_EXP: ExpInt = -Self::MAX_EXP + 1;
 
@@ -2608,7 +2608,7 @@ mod sig {
     ///
     /// `(n - 1) * (n - 1) + 2 * (n - 1) == (n - 1) * (n + 1)`
     ///
-    /// which is less than n^2.
+    /// which is less than n<sup>2</sup>.
     pub(super) fn widening_mul(a: Limb, b: Limb) -> [Limb; 2] {
         let mut wide = [0, 0];