From 078820613fc5eb780ae24c0fbc734f51e4773009 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Thu, 9 Jan 2020 03:48:26 +0900 Subject: [PATCH] Fix links and paths --- src/appendix/code-index.md | 10 +++++----- src/hir.md | 22 +++++++++++----------- src/rustdoc.md | 2 +- src/ty.md | 32 ++++++++++++++++---------------- 4 files changed, 33 insertions(+), 33 deletions(-) diff --git a/src/appendix/code-index.md b/src/appendix/code-index.md index 67030bee..39e16c1c 100644 --- a/src/appendix/code-index.md +++ b/src/appendix/code-index.md @@ -6,14 +6,14 @@ compiler. Item | Kind | Short description | Chapter | Declaration ----------------|----------|-----------------------------|--------------------|------------------- -`BodyId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.BodyId.html) +`BodyId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc_hir/hir.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.BodyId.html) `Compiler` | struct | Represents a compiler session and can be used to drive a compilation. | [The Rustc Driver and Interface] | [src/librustc_interface/interface.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html) -`ast::Crate` | struct | A syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.Crate.html) -`hir::Crate` | struct | A more abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Crate.html) -`DefId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc/hir/def_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/def_id/struct.DefId.html) +`ast::Crate` | struct | A syntax-level representation of a parsed crate | [The parser] | [src/libsyntax/ast.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.Crate.html) +`rustc_hir::Crate` | struct | A more abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc_hir/hir.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Crate.html) +`DefId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc_hir/def_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html) `DiagnosticBuilder` | struct | A struct for building up compiler diagnostics, such as errors or lints | [Emitting Diagnostics] | [src/librustc_errors/diagnostic_builder.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.DiagnosticBuilder.html) `DocContext` | struct | A state container used by rustdoc when crawling through a crate to gather its documentation | [Rustdoc] | [src/librustdoc/core.rs](https://github.com/rust-lang/rust/blob/master/src/librustdoc/core.rs) -`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.HirId.html) +`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc_hir/hir_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html) `NodeId` | struct | One of four types of HIR node identifiers. Being phased out | [Identifiers in the HIR] | [src/libsyntax/ast.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.NodeId.html) `P` | struct | An owned immutable smart pointer. By contrast, `&T` is not owned, and `Box` is not immutable. | None | [src/syntax/ptr.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ptr/struct.P.html) `ParamEnv` | struct | Information about generic parameters or `Self`, useful for working with associated or generic items | [Parameter Environment] | [src/librustc/ty/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.ParamEnv.html) diff --git a/src/hir.md b/src/hir.md index 67becec1..60a3c3b8 100644 --- a/src/hir.md +++ b/src/hir.md @@ -27,7 +27,7 @@ data structure basically just contains the root module, the HIR `Crate` structure contains a number of maps and other things that serve to organize the content of the crate for easier access. -[`Crate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Crate.html +[`Crate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Crate.html For example, the contents of individual items (e.g. modules, functions, traits, impls, etc) in the HIR are not immediately @@ -45,7 +45,7 @@ struct) would only have the **`ItemId`** `I` of `bar()`. To get the details of the function `bar()`, we would lookup `I` in the `items` map. -[`Mod`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Mod.html +[`Mod`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Mod.html One nice result from this representation is that one can iterate over all items in the crate by iterating over the key-value pairs @@ -55,14 +55,14 @@ as well as "bodies" (explained below). The other reason to set up the representation this way is for better integration with incremental compilation. This way, if you gain access -to an [`&hir::Item`] (e.g. for the mod `foo`), you do not immediately +to an [`&rustc_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 invoke some function to lookup the contents of `bar()` given its id; this gives the compiler a chance to observe that you accessed the data for `bar()`, and then record the dependency. -[`&hir::Item`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Item.html +[`&rustc_hir::Item`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Item.html @@ -97,9 +97,9 @@ sorts of identifiers in active use: tree causes the [`NodeId`]s of all subsequent code in the crate to change. This is terrible for incremental compilation, as you can perhaps imagine. -[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/def_id/struct.DefId.html -[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.HirId.html -[`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.BodyId.html +[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html +[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html +[`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.BodyId.html [`NodeId`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.NodeId.html We also have an internal map to go from `DefId` to what’s called "Def path". "Def path" is like a @@ -141,9 +141,9 @@ that `n` must be some HIR expression, you can do [`&hir::Expr`][Expr], panicking if `n` is not in fact an expression. [find]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.find -[`Node`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/enum.Node.html +[`Node`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/enum.Node.html [expect_expr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.expect_expr -[Expr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Expr.html +[Expr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Expr.html Finally, you can use the HIR map to find the parents of nodes, via calls like [`tcx.hir.get_parent_node(n)`][get_parent_node]. @@ -152,7 +152,7 @@ calls like [`tcx.hir.get_parent_node(n)`][get_parent_node]. ### HIR Bodies -A [`hir::Body`] represents some kind of executable code, such as the body +A [`rustc_hir::Body`] represents some kind of executable code, such as the body of a function/closure or the definition of a constant. Bodies are associated with an **owner**, which is typically some kind of item (e.g. an `fn()` or `const`), but could also be a closure expression @@ -160,6 +160,6 @@ associated with an **owner**, which is typically some kind of item associated with a given def-id ([`maybe_body_owned_by`]) or to find the owner of a body ([`body_owner_def_id`]). -[`hir::Body`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Body.html +[`rustc_hir::Body`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Body.html [`maybe_body_owned_by`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.maybe_body_owned_by [`body_owner_def_id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.body_owner_def_id diff --git a/src/rustdoc.md b/src/rustdoc.md index 318a8e2e..fc964b18 100644 --- a/src/rustdoc.md +++ b/src/rustdoc.md @@ -84,7 +84,7 @@ is the `impl Clean for visit_ast::RustdocVisitor`, which is called by You see, I actually lied a little earlier: There's another AST transformation that happens before the events in `clean/mod.rs`. In `visit_ast.rs` is the -type `RustdocVisitor`, which *actually* crawls a `hir::Crate` to get the first +type `RustdocVisitor`, which *actually* crawls a `rustc_hir::Crate` to get the first intermediate representation, defined in `doctree.rs`. This pass is mainly to get a few intermediate wrappers around the HIR types and to process visibility and inlining. This is where `#[doc(inline)]`, `#[doc(no_inline)]`, and diff --git a/src/ty.md b/src/ty.md index c9d2feba..870e886d 100644 --- a/src/ty.md +++ b/src/ty.md @@ -15,13 +15,13 @@ quite a few modules and types for `Ty` in the compiler ([Ty documentation][ty]). [ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/index.html The specific `Ty` we are referring to is [`rustc::ty::Ty`][ty_ty] (and not -[`rustc::hir::Ty`][hir_ty]). The distinction is important, so we will discuss it first before going +[`rustc_hir::Ty`][hir_ty]). The distinction is important, so we will discuss it first before going into the details of `ty::Ty`. [ty_ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/type.Ty.html -[hir_ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Ty.html +[hir_ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.Ty.html -## `hir::Ty` vs `ty::Ty` +## `rustc_hir::Ty` vs `ty::Ty` The HIR in rustc can be thought of as the high-level intermediate representation. It is more or less the AST (see [this chapter](hir.md)) as it represents the @@ -30,7 +30,7 @@ representation of types, but in reality it reflects more of what the user wrote, wrote so as to represent that type. In contrast, `ty::Ty` represents the semantics of a type, that is, the *meaning* of what the user -wrote. For example, `hir::Ty` would record the fact that a user used the name `u32` twice in their +wrote. For example, `rustc_hir::Ty` would record the fact that a user used the name `u32` twice in their program, but the `ty::Ty` would record the fact that both usages refer to the same type. **Example: `fn foo(x: u32) → u32 { }`** In this function we see that `u32` appears twice. We know @@ -49,26 +49,26 @@ look like `fn foo<'a>(x: &'a u32) -> &'a u32)`. In the HIR level, these things are not spelled out and you can say the picture is rather incomplete. However, at the `ty::Ty` level, these details are added and it is complete. Moreover, we will have exactly one `ty::Ty` for a given type, like `u32`, and that `ty::Ty` is used for all `u32`s in the -whole program, not a specific usage, unlike `hir::Ty`. +whole program, not a specific usage, unlike `rustc_hir::Ty`. Here is a summary: -| [`hir::Ty`][hir_ty] | [`ty::Ty`][ty_ty] | +| [`rustc_hir::Ty`][hir_ty] | [`ty::Ty`][ty_ty] | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Describe the *syntax* of a type: what the user wrote (with some desugaring). | Describe the *semantics* of a type: the meaning of what the user wrote. | -| Each `hir::Ty` has its own spans corresponding to the appropriate place in the program. | Doesn’t correspond to a single place in the user’s program. | -| `hir::Ty` has generics and lifetimes; however, some of those lifetimes are special markers like [`LifetimeName::Implicit`][implicit]. | `ty::Ty` has the full type, including generics and lifetimes, even if the user left them out | -| `fn foo(x: u32) → u32 { }` - Two `hir::Ty` representing each usage of `u32`. Each has its own `Span`s, etc.- `hir::Ty` doesn’t tell us that both are the same type | `fn foo(x: u32) → u32 { }` - One `ty::Ty` for all instances of `u32` throughout the program.- `ty::Ty` tells us that both usages of `u32` mean the same type. | -| `fn foo(x: &u32) -> &u32)`- Two `hir::Ty` again.- Lifetimes for the references show up in the `hir::Ty`s using a special marker, [`LifetimeName::Implicit`][implicit]. | `fn foo(x: &u32) -> &u32)`- A single `ty::Ty`.- The `ty::Ty` has the hidden lifetime param | +| Each `rustc_hir::Ty` has its own spans corresponding to the appropriate place in the program. | Doesn’t correspond to a single place in the user’s program. | +| `rustc_hir::Ty` has generics and lifetimes; however, some of those lifetimes are special markers like [`LifetimeName::Implicit`][implicit]. | `ty::Ty` has the full type, including generics and lifetimes, even if the user left them out | +| `fn foo(x: u32) → u32 { }` - Two `rustc_hir::Ty` representing each usage of `u32`. Each has its own `Span`s, etc.- `rustc_hir::Ty` doesn’t tell us that both are the same type | `fn foo(x: u32) → u32 { }` - One `ty::Ty` for all instances of `u32` throughout the program.- `ty::Ty` tells us that both usages of `u32` mean the same type. | +| `fn foo(x: &u32) -> &u32)`- Two `rustc_hir::Ty` again.- Lifetimes for the references show up in the `rustc_hir::Ty`s using a special marker, [`LifetimeName::Implicit`][implicit]. | `fn foo(x: &u32) -> &u32)`- A single `ty::Ty`.- The `ty::Ty` has the hidden lifetime param | -[implicit]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/enum.LifetimeName.html#variant.Implicit +[implicit]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/enum.LifetimeName.html#variant.Implicit **Order** HIR is built directly from the AST, so it happens before any `ty::Ty` is produced. After HIR is built, some basic type inference and type checking is done. During the type inference, we figure out what the `ty::Ty` of everything is and we also check if the type of something is ambiguous. The `ty::Ty` then, is used for type checking while making sure everything has the expected type. The [`astconv` module][astconv], is where the code responsible for converting a -`hir::Ty` into a `ty::Ty` is located. This occurs during the type-checking phase, but also in other +`rustc_hir::Ty` into a `ty::Ty` is located. This occurs during the type-checking phase, but also in other parts of the compiler that want to ask questions like "what argument types does this function expect"?. @@ -85,7 +85,7 @@ we determine that they semantically are the same type and that’s the `ty::Ty` Consider another example: `fn foo(x: T) -> u32` and suppose that someone invokes `foo::(0)`. This means that `T` and `u32` (in this invocation) actually turns out to be the same type, so we -would eventually end up with the same `ty::Ty` in the end, but we have distinct `hir::Ty`. (This is +would eventually end up with the same `ty::Ty` in the end, but we have distinct `rustc_hir::Ty`. (This is a bit over-simplified, though, since during type checking, we would check the function generically and would still have a `T` distinct from `u32`. Later, when doing code generation, we would always be handling "monomorphized" (fully substituted) versions of each function, and hence we would know @@ -104,7 +104,7 @@ mod b { } ``` -Here the type `X` will vary depending on context, clearly. If you look at the `hir::Ty`, you will +Here the type `X` will vary depending on context, clearly. If you look at the `rustc_hir::Ty`, you will get back that `X` is an alias in both cases (though it will be mapped via name resolution to distinct aliases). But if you look at the `ty::Ty` signature, it will be either `fn(u32) -> u32` or `fn(i32) -> i32` (with type aliases fully expanded). @@ -466,7 +466,7 @@ You may have a couple of followup questions… replace a `SubstRef` with another list of types. [Here is an example of actually using `subst` in the compiler][substex]. The exact details are not -too important, but in this piece of code, we happen to be converting from the `hir::Ty` to a real +too important, but in this piece of code, we happen to be converting from the `rustc_hir::Ty` to a real `ty::Ty`. You can see that we first get some substitutions (`substs`). Then we call `type_of` to get a type and call `ty.subst(substs)` to get a new version of `ty` with the substitutions made. @@ -475,7 +475,7 @@ get a type and call `ty.subst(substs)` to get a new version of `ty` with the sub **Note on indices:** It is possible for the indices in `Param` to not match with what we expect. For example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type. These sorts of errors would be caught earlier in the compiler when translating -from a `hir::Ty` to a `ty::Ty`. If they occur later, that is a compiler bug. +from a `rustc_hir::Ty` to a `ty::Ty`. If they occur later, that is a compiler bug. ### `TypeFoldable` and `TypeFolder`