Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make HIR identifiers table more discoverable #420

Open
Nashenas88 opened this issue Aug 7, 2019 · 4 comments

Comments

@Nashenas88
Copy link
Contributor

commented Aug 7, 2019

On https://rust-lang.github.io/rustc-guide/hir.html when I came across the list in the section "Identifiers in the HIR", I instantly wished I had seen it earlier in the book. I made a lot of earlier details easier to understand. It would have also been helpful if descriptions like this were available in the glossary.

@spastorino

This comment has been minimized.

Copy link
Member

commented Aug 7, 2019

I guess you're talking about this https://rust-lang.github.io/rustc-guide/hir.html#identifiers-in-the-hir right?. DefId and HirId are already in the glossary, what you mean is to add NodeId and BodyId?

@Nashenas88

This comment has been minimized.

Copy link
Contributor Author

commented Aug 15, 2019

NodeId is already there, but it would be helpful to add BodyId. However, I was more referring to the fact that the explanations in the link above are much easier to understand than the simple sentences in the glossary. Having a link from the glossary to those extended explanations would be really helpful, I think. I'm a big fan of bidirectional linking in documentation.

@Nashenas88

This comment has been minimized.

Copy link
Contributor Author

commented Aug 15, 2019

For example, this is the existing entry for DefId in the glossary:

DefId | an index identifying a definition (see librustc/hir/def_id.rs). Uniquely identifies a DefPath.

compared to the chart in the hir page:

DefId, which primarily names "definitions" or top-level items.

  • You can think of a DefId as being shorthand for a very explicit and complete path, like std::collections::HashMap. However, these paths are able to name things that are not nameable in normal Rust (e.g. impls), and they also include extra information about the crate (such as its version number, as two versions of the same crate can co-exist).
  • A DefId really consists of two parts, a CrateNum (which identifies the crate) and a DefIndex (which indexes into a list of items that is maintained per crate).

If every instance of DefId linked to the glossary, and the glossary linked to the more detailed description, it would allow people to easily find this very helpful explanation. Or would it make more sense to expand the description in the glossary so it's as helpful as the initial entry? Maybe also include a link in the glossary to the implementation in the source as the hir page documentation does?

@spastorino

This comment has been minimized.

Copy link
Member

commented Aug 15, 2019

NodeId is already there, but it would be helpful to add BodyId. However, I was more referring to the fact that the explanations in the link above are much easier to understand than the simple sentences in the glossary. Having a link from the glossary to those extended explanations would be really helpful, I think. I'm a big fan of bidirectional linking in documentation.

Agree with this really. Please provide a PR if you can/want :).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.