upgrade comments on MIR structures and functions to doc comments

src/librustc/mir/repr.rs

@@ -144,33 +144,33 @@ pub enum BorrowKind {
 ///////////////////////////////////////////////////////////////////////////
 // Variables and temps
 
-// A "variable" is a binding declared by the user as part of the fn
-// decl, a let, etc.
+/// A "variable" is a binding declared by the user as part of the fn
+/// decl, a let, etc.
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub struct VarDecl<'tcx> {
     pub mutability: Mutability,
     pub name: Name,
     pub ty: Ty<'tcx>,
 }
 
-// A "temp" is a temporary that we place on the stack. They are
-// anonymous, always mutable, and have only a type.
+/// A "temp" is a temporary that we place on the stack. They are
+/// anonymous, always mutable, and have only a type.
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub struct TempDecl<'tcx> {
     pub ty: Ty<'tcx>,
 }
 
-// A "arg" is one of the function's formal arguments. These are
-// anonymous and distinct from the bindings that the user declares.
-//
-// For example, in this function:
-//
-// ```
-// fn foo((x, y): (i32, u32)) { ... }
-// ```
-//
-// there is only one argument, of type `(i32, u32)`, but two bindings
-// (`x` and `y`).
+/// A "arg" is one of the function's formal arguments. These are
+/// anonymous and distinct from the bindings that the user declares.
+///
+/// For example, in this function:
+///
+/// ```
+/// fn foo((x, y): (i32, u32)) { ... }
+/// ```
+///
+/// there is only one argument, of type `(i32, u32)`, but two bindings
+/// (`x` and `y`).
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub struct ArgDecl<'tcx> {
     pub ty: Ty<'tcx>,
@@ -495,7 +495,8 @@ pub enum StatementKind<'tcx> {
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq, RustcEncodable, RustcDecodable)]
 pub enum DropKind {
-    Free, // free a partially constructed box, should go away eventually
+    /// free a partially constructed box, should go away eventually
+    Free,
     Deep
 }
 
@@ -552,24 +553,27 @@ pub enum ProjectionElem<'tcx, V> {
     Field(Field),
     Index(V),
 
-    // These indices are generated by slice patterns. Easiest to explain
-    // by example:
-    //
-    // ```
-    // [X, _, .._, _, _] => { offset: 0, min_length: 4, from_end: false },
-    // [_, X, .._, _, _] => { offset: 1, min_length: 4, from_end: false },
-    // [_, _, .._, X, _] => { offset: 2, min_length: 4, from_end: true },
-    // [_, _, .._, _, X] => { offset: 1, min_length: 4, from_end: true },
-    // ```
+    /// These indices are generated by slice patterns. Easiest to explain
+    /// by example:
+    ///
+    /// ```
+    /// [X, _, .._, _, _] => { offset: 0, min_length: 4, from_end: false },
+    /// [_, X, .._, _, _] => { offset: 1, min_length: 4, from_end: false },
+    /// [_, _, .._, X, _] => { offset: 2, min_length: 4, from_end: true },
+    /// [_, _, .._, _, X] => { offset: 1, min_length: 4, from_end: true },
+    /// ```
     ConstantIndex {
-        offset: u32,      // index or -index (in Python terms), depending on from_end
-        min_length: u32,  // thing being indexed must be at least this long
-        from_end: bool,   // counting backwards from end?
+        /// index or -index (in Python terms), depending on from_end
+        offset: u32,
+        /// thing being indexed must be at least this long
+        min_length: u32,
+        /// counting backwards from end?
+        from_end: bool,
     },
 
-    // "Downcast" to a variant of an ADT. Currently, we only introduce
-    // this for ADTs with more than one variant. It may be better to
-    // just introduce it always, or always for enums.
+    /// "Downcast" to a variant of an ADT. Currently, we only introduce
+    /// this for ADTs with more than one variant. It may be better to
+    /// just introduce it always, or always for enums.
     Downcast(AdtDef<'tcx>, usize),
 }
 
@@ -654,9 +658,9 @@ impl<'tcx> Debug for Lvalue<'tcx> {
 ///////////////////////////////////////////////////////////////////////////
 // Operands
 //
-// These are values that can appear inside an rvalue (or an index
-// lvalue). They are intentionally limited to prevent rvalues from
-// being nested in one another.
+/// These are values that can appear inside an rvalue (or an index
+/// lvalue). They are intentionally limited to prevent rvalues from
+/// being nested in one another.
 
 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable)]
 pub enum Operand<'tcx> {
@@ -675,20 +679,20 @@ impl<'tcx> Debug for Operand<'tcx> {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// Rvalues
+/// Rvalues
 
 #[derive(Clone, RustcEncodable, RustcDecodable)]
 pub enum Rvalue<'tcx> {
-    // x (either a move or copy, depending on type of x)
+    /// x (either a move or copy, depending on type of x)
     Use(Operand<'tcx>),
 
-    // [x; 32]
+    /// [x; 32]
     Repeat(Operand<'tcx>, TypedConstVal<'tcx>),
 
-    // &x or &mut x
+    /// &x or &mut x
     Ref(Region, BorrowKind, Lvalue<'tcx>),
 
-    // length of a [X] or [X;n] value
+    /// length of a [X] or [X;n] value
     Len(Lvalue<'tcx>),
 
     Cast(CastKind, Operand<'tcx>, Ty<'tcx>),
@@ -697,21 +701,21 @@ pub enum Rvalue<'tcx> {
 
     UnaryOp(UnOp, Operand<'tcx>),
 
-    // Creates an *uninitialized* Box
+    /// Creates an *uninitialized* Box
     Box(Ty<'tcx>),
 
-    // Create an aggregate value, like a tuple or struct.  This is
-    // only needed because we want to distinguish `dest = Foo { x:
-    // ..., y: ... }` from `dest.x = ...; dest.y = ...;` in the case
-    // that `Foo` has a destructor. These rvalues can be optimized
-    // away after type-checking and before lowering.
+    /// Create an aggregate value, like a tuple or struct.  This is
+    /// only needed because we want to distinguish `dest = Foo { x:
+    /// ..., y: ... }` from `dest.x = ...; dest.y = ...;` in the case
+    /// that `Foo` has a destructor. These rvalues can be optimized
+    /// away after type-checking and before lowering.
     Aggregate(AggregateKind<'tcx>, Vec<Operand<'tcx>>),
 
-    // Generates a slice of the form `&input[from_start..L-from_end]`
-    // where `L` is the length of the slice. This is only created by
-    // slice pattern matching, so e.g. a pattern of the form `[x, y,
-    // .., z]` might create a slice with `from_start=2` and
-    // `from_end=1`.
+    /// Generates a slice of the form `&input[from_start..L-from_end]`
+    /// where `L` is the length of the slice. This is only created by
+    /// slice pattern matching, so e.g. a pattern of the form `[x, y,
+    /// .., z]` might create a slice with `from_start=2` and
+    /// `from_end=1`.
     Slice {
         input: Lvalue<'tcx>,
         from_start: usize,
@@ -878,11 +882,11 @@ impl<'tcx> Debug for Rvalue<'tcx> {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// Constants
-//
-// Two constants are equal if they are the same constant. Note that
-// this does not necessarily mean that they are "==" in Rust -- in
-// particular one must be wary of `NaN`!
+/// Constants
+///
+/// Two constants are equal if they are the same constant. Note that
+/// this does not necessarily mean that they are "==" in Rust -- in
+/// particular one must be wary of `NaN`!
 
 #[derive(Clone, PartialEq, RustcEncodable, RustcDecodable)]
 pub struct Constant<'tcx> {

src/librustc_mir/build/mod.rs

@@ -34,10 +34,10 @@ struct CFG<'tcx> {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// The `BlockAnd` "monad" packages up the new basic block along with a
-// produced value (sometimes just unit, of course). The `unpack!`
-// macro (and methods below) makes working with `BlockAnd` much more
-// convenient.
+/// The `BlockAnd` "monad" packages up the new basic block along with a
+/// produced value (sometimes just unit, of course). The `unpack!`
+/// macro (and methods below) makes working with `BlockAnd` much more
+/// convenient.
 
 #[must_use] // if you don't use one of these results, you're leaving a dangling edge
 pub struct BlockAnd<T>(BasicBlock, T);
@@ -77,7 +77,7 @@ macro_rules! unpack {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// construct() -- the main entry point for building MIR for a function
+/// the main entry point for building MIR for a function
 
 pub fn construct<'a,'tcx>(hir: Cx<'a,'tcx>,
                           _span: Span,

src/librustc_mir/hair/mod.rs

@@ -85,33 +85,33 @@ pub enum StmtKind<'tcx> {
     },
 }
 
-// The Hair trait implementor translates their expressions (`&'tcx H::Expr`)
-// into instances of this `Expr` enum. This translation can be done
-// basically as lazilly or as eagerly as desired: every recursive
-// reference to an expression in this enum is an `ExprRef<'tcx>`, which
-// may in turn be another instance of this enum (boxed), or else an
-// untranslated `&'tcx H::Expr`. Note that instances of `Expr` are very
-// shortlived. They are created by `Hair::to_expr`, analyzed and
-// converted into MIR, and then discarded.
-//
-// If you compare `Expr` to the full compiler AST, you will see it is
-// a good bit simpler. In fact, a number of the more straight-forward
-// MIR simplifications are already done in the impl of `Hair`. For
-// example, method calls and overloaded operators are absent: they are
-// expected to be converted into `Expr::Call` instances.
+/// The Hair trait implementor translates their expressions (`&'tcx H::Expr`)
+/// into instances of this `Expr` enum. This translation can be done
+/// basically as lazilly or as eagerly as desired: every recursive
+/// reference to an expression in this enum is an `ExprRef<'tcx>`, which
+/// may in turn be another instance of this enum (boxed), or else an
+/// untranslated `&'tcx H::Expr`. Note that instances of `Expr` are very
+/// shortlived. They are created by `Hair::to_expr`, analyzed and
+/// converted into MIR, and then discarded.
+///
+/// If you compare `Expr` to the full compiler AST, you will see it is
+/// a good bit simpler. In fact, a number of the more straight-forward
+/// MIR simplifications are already done in the impl of `Hair`. For
+/// example, method calls and overloaded operators are absent: they are
+/// expected to be converted into `Expr::Call` instances.
 #[derive(Clone, Debug)]
 pub struct Expr<'tcx> {
-    // type of this expression
+    /// type of this expression
     pub ty: Ty<'tcx>,
 
-    // lifetime of this expression if it should be spilled into a
-    // temporary; should be None only if in a constant context
+    /// lifetime of this expression if it should be spilled into a
+    /// temporary; should be None only if in a constant context
     pub temp_lifetime: Option<CodeExtent>,
 
-    // span of the expression in the source
+    /// span of the expression in the source
     pub span: Span,
 
-    // kind of expression
+    /// kind of expression
     pub kind: ExprKind<'tcx>,
 }
 
@@ -194,7 +194,8 @@ pub enum ExprKind<'tcx> {
     VarRef {
         id: ast::NodeId,
     },
-    SelfRef, // first argument, used for self in a closure
+    /// first argument, used for self in a closure
+    SelfRef,
     StaticRef {
         id: DefId,
     },
@@ -278,7 +279,7 @@ pub enum LogicalOp {
 pub enum PatternKind<'tcx> {
     Wild,
 
-    // x, ref x, x @ P, etc
+    /// x, ref x, x @ P, etc
     Binding {
         mutability: Mutability,
         name: ast::Name,
@@ -288,21 +289,22 @@ pub enum PatternKind<'tcx> {
         subpattern: Option<Pattern<'tcx>>,
     },
 
-    // Foo(...) or Foo{...} or Foo, where `Foo` is a variant name from an adt with >1 variants
+    /// Foo(...) or Foo{...} or Foo, where `Foo` is a variant name from an adt with >1 variants
     Variant {
         adt_def: AdtDef<'tcx>,
         variant_index: usize,
         subpatterns: Vec<FieldPattern<'tcx>>,
     },
 
-    // (...), Foo(...), Foo{...}, or Foo, where `Foo` is a variant name from an adt with 1 variant
+    /// (...), Foo(...), Foo{...}, or Foo, where `Foo` is a variant name from an adt with 1 variant
     Leaf {
         subpatterns: Vec<FieldPattern<'tcx>>,
     },
 
+    /// box P, &P, &mut P, etc
     Deref {
         subpattern: Pattern<'tcx>,
-    }, // box P, &P, &mut P, etc
+    },
 
     Constant {
         value: ConstVal,
@@ -313,14 +315,14 @@ pub enum PatternKind<'tcx> {
         hi: Literal<'tcx>,
     },
 
-    // matches against a slice, checking the length and extracting elements
+    /// matches against a slice, checking the length and extracting elements
     Slice {
         prefix: Vec<Pattern<'tcx>>,
         slice: Option<Pattern<'tcx>>,
         suffix: Vec<Pattern<'tcx>>,
     },
 
-    // fixed match against an array, irrefutable
+    /// fixed match against an array, irrefutable
     Array {
         prefix: Vec<Pattern<'tcx>>,
         slice: Option<Pattern<'tcx>>,