upgrade comments on MIR structures and functions to doc comments
This commit is contained in:
Oliver Schneider
parent
8c77ffb484
commit
4e44ef1e29
@ -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<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> {
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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>>,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user