From 61ba32b768573561c3aa790d80cc934c3ce77bea Mon Sep 17 00:00:00 2001 From: Cameron Steffen Date: Sat, 30 Apr 2022 12:27:01 -0500 Subject: [PATCH] Update intravisit docs --- compiler/rustc_hir/src/intravisit.rs | 60 ++++++++++++------------- compiler/rustc_hir/src/itemlikevisit.rs | 10 ++--- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/compiler/rustc_hir/src/intravisit.rs b/compiler/rustc_hir/src/intravisit.rs index d41b85fd20f7b..977c0eb3cd2bc 100644 --- a/compiler/rustc_hir/src/intravisit.rs +++ b/compiler/rustc_hir/src/intravisit.rs @@ -163,10 +163,15 @@ impl<'hir> Map<'hir> for ! { pub mod nested_filter { use super::Map; - /// Specifies what nested things a visitor wants to visit. The most - /// common choice is `OnlyBodies`, which will cause the visitor to - /// visit fn bodies for fns that it encounters, but skip over nested - /// item-like things. + /// Specifies what nested things a visitor wants to visit. By "nested + /// things", we are referring to bits of HIR that are not directly embedded + /// within one another but rather indirectly, through a table in the crate. + /// This is done to control dependencies during incremental compilation: the + /// non-inline bits of HIR can be tracked and hashed separately. + /// + /// The most common choice is `OnlyBodies`, which will cause the visitor to + /// visit fn bodies for fns that it encounters, and closure bodies, but + /// skip over nested item-like things. /// /// See the comments on `ItemLikeVisitor` for more details on the overall /// visit strategy. @@ -217,27 +222,23 @@ use nested_filter::NestedFilter; pub trait Visitor<'v>: Sized { // this type should not be overridden, it exists for convenient usage as `Self::Map` type Map: Map<'v> = >::Map; - type NestedFilter: NestedFilter<'v> = nested_filter::None; /////////////////////////////////////////////////////////////////////////// // Nested items. - /// The default versions of the `visit_nested_XXX` routines invoke - /// this method to get a map to use. By selecting an enum variant, - /// you control which kinds of nested HIR are visited; see - /// `NestedVisitorMap` for details. By "nested HIR", we are - /// referring to bits of HIR that are not directly embedded within - /// one another but rather indirectly, through a table in the - /// crate. This is done to control dependencies during incremental - /// compilation: the non-inline bits of HIR can be tracked and - /// hashed separately. + /// Override this type to control which nested HIR are visited; see + /// [`NestedFilter`] for details. If you override this type, you + /// must also override [`nested_visit_map`](Self::nested_visit_map). /// /// **If for some reason you want the nested behavior, but don't - /// have a `Map` at your disposal:** then you should override the - /// `visit_nested_XXX` methods, and override this method to - /// `panic!()`. This way, if a new `visit_nested_XXX` variant is - /// added in the future, we will see the panic in your code and - /// fix it appropriately. + /// have a `Map` at your disposal:** then override the + /// `visit_nested_XXX` methods. If a new `visit_nested_XXX` variant is + /// added in the future, it will cause a panic which can be detected + /// and fixed appropriately. + type NestedFilter: NestedFilter<'v> = nested_filter::None; + + /// If `type NestedFilter` is set to visit nested items, this method + /// must also be overridden to provide a map to retrieve nested items. fn nested_visit_map(&mut self) -> Self::Map { panic!( "nested_visit_map must be implemented or consider using \ @@ -245,14 +246,14 @@ pub trait Visitor<'v>: Sized { ); } - /// Invoked when a nested item is encountered. By default does - /// nothing unless you override `nested_visit_map` to return other than - /// `None`, in which case it will walk the item. **You probably - /// don't want to override this method** -- instead, override - /// `nested_visit_map` or use the "shallow" or "deep" visit - /// patterns described on `itemlikevisit::ItemLikeVisitor`. The only - /// reason to override this method is if you want a nested pattern - /// but cannot supply a `Map`; see `nested_visit_map` for advice. + /// Invoked when a nested item is encountered. By default, when + /// `Self::NestedFilter` is `nested_filter::None`, this method does + /// nothing. **You probably don't want to override this method** -- + /// instead, override [`Self::NestedFilter`] or use the "shallow" or + /// "deep" visit patterns described on + /// `itemlikevisit::ItemLikeVisitor`. The only reason to override + /// this method is if you want a nested pattern but cannot supply a + /// [`Map`]; see `nested_visit_map` for advice. fn visit_nested_item(&mut self, id: ItemId) { if Self::NestedFilter::INTER { let item = self.nested_visit_map().item(id); @@ -291,9 +292,8 @@ pub trait Visitor<'v>: Sized { } /// Invoked to visit the body of a function, method or closure. Like - /// visit_nested_item, does nothing by default unless you override - /// `nested_visit_map` to return other than `None`, in which case it will walk - /// the body. + /// `visit_nested_item`, does nothing by default unless you override + /// `Self::NestedFilter`. fn visit_nested_body(&mut self, id: BodyId) { if Self::NestedFilter::INTRA { let body = self.nested_visit_map().body(id); diff --git a/compiler/rustc_hir/src/itemlikevisit.rs b/compiler/rustc_hir/src/itemlikevisit.rs index db70002c2d66a..b2c6ca1354f10 100644 --- a/compiler/rustc_hir/src/itemlikevisit.rs +++ b/compiler/rustc_hir/src/itemlikevisit.rs @@ -17,8 +17,8 @@ use super::{ForeignItem, ImplItem, Item, TraitItem}; /// an item, but don't care about how item-like things are nested /// within one another. /// - Example: Examine each expression to look for its type and do some check or other. -/// - How: Implement `intravisit::Visitor` and override the `nested_visit_map()` method -/// to return `NestedVisitorMap::OnlyBodies` and use +/// - How: Implement `intravisit::Visitor` and override the `NestedFilter` type to +/// `nested_filter::OnlyBodies` (and implement `nested_visit_map`), and use /// `tcx.hir().visit_all_item_likes(&mut visitor.as_deep_visitor())`. Within your /// `intravisit::Visitor` impl, implement methods like `visit_expr()` (don't forget to invoke /// `intravisit::walk_expr()` to keep walking the subparts). @@ -29,9 +29,9 @@ use super::{ForeignItem, ImplItem, Item, TraitItem}; /// item-like things. /// - Example: Lifetime resolution, which wants to bring lifetimes declared on the /// impl into scope while visiting the impl-items, and then back out again. -/// - How: Implement `intravisit::Visitor` and override the `nested_visit_map()` method -/// to return `NestedVisitorMap::All`. Walk your crate with `intravisit::walk_crate()` -/// invoked on `tcx.hir().krate()`. +/// - How: Implement `intravisit::Visitor` and override the `NestedFilter` type to +/// `nested_filter::All` (and implement `nested_visit_map`). Walk your crate with +/// `tcx.hir().walk_toplevel_module(visitor)` invoked on `tcx.hir().krate()`. /// - Pro: Visitor methods for any kind of HIR node, not just item-like things. /// - Pro: Preserves nesting information /// - Con: Does not integrate well into dependency tracking.