From 4e44ef1e29932ad7ca69ddf6bc7ad4011a8bb3fa Mon Sep 17 00:00:00 2001 From: Oliver Schneider Date: Wed, 3 Feb 2016 13:25:07 +0100 Subject: [PATCH] upgrade comments on MIR structures and functions to doc comments --- src/librustc/mir/repr.rs | 114 ++++++++++++++++++---------------- src/librustc_mir/build/mod.rs | 10 +-- src/librustc_mir/hair/mod.rs | 54 ++++++++-------- 3 files changed, 92 insertions(+), 86 deletions(-) diff --git a/src/librustc/mir/repr.rs b/src/librustc/mir/repr.rs index 0fe39dcb7f9..988bf2c76a8 100644 --- a/src/librustc/mir/repr.rs +++ b/src/librustc/mir/repr.rs @@ -144,8 +144,8 @@ 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, @@ -153,24 +153,24 @@ pub struct VarDecl<'tcx> { 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>), - // 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> { diff --git a/src/librustc_mir/build/mod.rs b/src/librustc_mir/build/mod.rs index a7459d62368..86b34858189 100644 --- a/src/librustc_mir/build/mod.rs +++ b/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(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, diff --git a/src/librustc_mir/hair/mod.rs b/src/librustc_mir/hair/mod.rs index d87b25a094e..b356e3886d1 100644 --- a/src/librustc_mir/hair/mod.rs +++ b/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, - // 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>, }, - // 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>, }, - // (...), 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>, }, + /// 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>, slice: Option>, suffix: Vec>, }, - // fixed match against an array, irrefutable + /// fixed match against an array, irrefutable Array { prefix: Vec>, slice: Option>,