diff --git a/src/librustc/README.md b/src/librustc/README.md index f2abaa6f95730b094ab81d2ca91b2629ca2d80eb..a5a184ed48c5c0338fea18ae667162c7ad084c6c 100644 --- a/src/librustc/README.md +++ b/src/librustc/README.md @@ -57,11 +57,12 @@ rustc_trans rustc_borrowck ... rustc_metadata syntax_pos syntax_ext ``` - -The idea is that `rustc_driver`, at the top of this lattice, basically -defines the overall control-flow of the compiler. It doesn't have much -"real code", but instead ties together all of the code defined in the -other crates and defines the overall flow of execution. +The `rustc_driver` crate, at the top of this lattice, is effectively +the "main" function for the rust compiler. It doesn't have much "real +code", but instead ties together all of the code defined in the other +crates and defines the overall flow of execution. (As we transition +more and more to the [query model](ty/maps/README.md), however, the +"flow" of compilation is becoming less centrally defined.) At the other extreme, the `rustc` crate defines the common and pervasive data structures that all the rest of the compiler uses diff --git a/src/librustc/hir/README.md b/src/librustc/hir/README.md index d4f4e48963a342a60565116e9910069ed4286cc8..c832a897dee8b69389bea5402cef5b42b526afa9 100644 --- a/src/librustc/hir/README.md +++ b/src/librustc/hir/README.md @@ -45,10 +45,10 @@ The other reason to setup the representation this way is for better integration with incremental compilation. This way, if you gain access to a `&hir::Item` (e.g. for the mod `foo`), you do not immediately gain access to the contents of the function `bar()`. Instead, you only -gain access to the **id** for `bar()`, and you must some function to -lookup the contents of `bar()` given its id; this gives us a change to -observe that you accessed the data for `bar()` and record the -dependency. +gain access to the **id** for `bar()`, and you must invoke some +function to lookup the contents of `bar()` given its id; this gives us +a chance to observe that you accessed the data for `bar()` and record +the dependency. ### Identifiers in the HIR @@ -117,7 +117,3 @@ associated with an **owner**, which is typically some kind of item (e.g., `|x, y| x + y`). You can use the HIR map to find find the body associated with a given def-id (`maybe_body_owned_by()`) or to find the owner of a body (`body_owner_def_id()`). - - - - diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs index ea3cdbaad413efa0181e7bc651e414451ece18f0..c250695f361a644076fae40eb196ff9f660f5226 100644 --- a/src/librustc/hir/mod.rs +++ b/src/librustc/hir/mod.rs @@ -416,6 +416,7 @@ pub struct WhereEqPredicate { /// 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). #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Debug)] pub struct Crate { pub module: Mod, @@ -935,9 +936,9 @@ pub struct BodyId { /// (which is an expression), but also the argument patterns, since /// those are something that the caller doesn't really care about. /// -/// Example: +/// # Examples /// -/// ```rust +/// ``` /// fn foo((x, y): (u32, u32)) -> u32 { /// x + y /// } diff --git a/src/librustc/ty/README.md b/src/librustc/ty/README.md index 0416be8b9ab34d45e5a1e6e01729bc1ac0338839..4f63912a1e0d1a8f8269a5a6d491d4e6827bd322 100644 --- a/src/librustc/ty/README.md +++ b/src/librustc/ty/README.md @@ -21,7 +21,7 @@ tcx: TyCtxt<'a, 'gcx, 'tcx> As you can see, the `TyCtxt` type takes three lifetime parameters. These lifetimes are perhaps the most complex thing to understand about -the tcx. During rust compilation, we allocate most of our memory in +the tcx. During Rust compilation, we allocate most of our memory in **arenas**, which are basically pools of memory that get freed all at once. When you see a reference with a lifetime like `'tcx` or `'gcx`, you know that it refers to arena-allocated data (or data that lives as @@ -70,18 +70,24 @@ fn maybe_in_inference<'a, 'gcx, 'tcx>(tcx: TyCtxt<'a, 'gcx, 'tcx>, def_id: DefId ### Allocating and working with types -Rust types are represented using the `ty::Ty<'tcx>` type. This is in fact a simple type alias -for a reference with `'tcx` lifetime: +Rust types are represented using the `Ty<'tcx>` defined in the `ty` +module (not to be confused with the `Ty` struct from [the HIR]). This +is in fact a simple type alias for a reference with `'tcx` lifetime: ```rust pub type Ty<'tcx> = &'tcx TyS<'tcx>; ``` -The `TyS` struct defines the actual details of how a type is -represented. The most interesting part of it is the `sty` field, which -contains an enum that lets us test what sort of type this is. For -example, it is very common to see code that tests what sort of type you have -that looks roughly like so: +[the HIR]: ../hir/README.md + +You can basically ignore the `TyS` struct -- you will basically never +access it explicitly. We always pass it by reference using the +`Ty<'tcx>` alias -- the only exception I think is to define inherent +methods on types. Instances of `TyS` are only ever allocated in one of +the rustc arenas (never e.g. on the stack). + +One common operation on types is to **match** and see what kinds of +types they are. This is done by doing `match ty.sty`, sort of like this: ```rust fn test_type<'tcx>(ty: Ty<'tcx>) { @@ -92,10 +98,14 @@ fn test_type<'tcx>(ty: Ty<'tcx>) { } ``` -(Note though that doing such low-level tests on types during inference -can be risky, as there are may be inference variables and other things -to consider, or sometimes types are not yet known that will become -known later.). +The `sty` field (the origin of this name is unclear to me; perhaps +structural type?) is of type `TypeVariants<'tcx>`, which is an enum +definined all of the different kinds of types in the compiler. + +> NB: inspecting the `sty` field on types during type inference can be +> risky, as there are may be inference variables and other things to +> consider, or sometimes types are not yet known that will become +> known later.). To allocate a new type, you can use the various `mk_` methods defined on the `tcx`. These have names that correpond mostly to the various kinds @@ -114,13 +124,13 @@ any inference variables or other "temporary" types, they will be allocated in the global arena). However, the lifetime `'tcx` is always a safe approximation, so that is what you get back. -NB. Because types are interned, it is possible to compare them for -equality efficiently using `==` -- however, this is almost never what -you want to do unless you happen to be hashing and looking for -duplicates. This is because often in Rust there are multiple ways to -represent the same type, particularly once inference is involved. If -you are going to be testing for type equality, you probably need to -start looking into the inference code to do it right. +> NB. Because types are interned, it is possible to compare them for +> equality efficiently using `==` -- however, this is almost never what +> you want to do unless you happen to be hashing and looking for +> duplicates. This is because often in Rust there are multiple ways to +> represent the same type, particularly once inference is involved. If +> you are going to be testing for type equality, you probably need to +> start looking into the inference code to do it right. You can also find various common types in the tcx itself by accessing `tcx.types.bool`, `tcx.types.char`, etc (see `CommonTypes` for more). @@ -153,7 +163,3 @@ In particular, since they are so common, the `Ty` and `TyCtxt` types are imported directly. Other types are often referenced with an explicit `ty::` prefix (e.g., `ty::TraitRef<'tcx>`). But some modules choose to import a larger or smaller set of names explicitly. - - - - diff --git a/src/librustc/ty/context.rs b/src/librustc/ty/context.rs index 6a95c62a303f4478cab26a7e1eb6952a096867a3..874bb426dc509f893006e180f2a9a270deb4057f 100644 --- a/src/librustc/ty/context.rs +++ b/src/librustc/ty/context.rs @@ -793,11 +793,10 @@ fn new(interners: &CtxtInterners<'tcx>) -> CommonTypes<'tcx> { } } -/// The central data structure of the compiler. Keeps track of all the -/// information that typechecker generates so that so that it can be -/// reused and doesn't have to be redone later on. -/// -/// See [the README](README.md) for more deatils. +/// 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. #[derive(Copy, Clone)] pub struct TyCtxt<'a, 'gcx: 'a+'tcx, 'tcx: 'a> { gcx: &'a GlobalCtxt<'gcx>,