Auto merge of #43605 - RalfJung:mapdoc, r=michaelwoerister

Improve hir::map::Map::get_parent_node doc

The documentation says
```
    /// Similar to get_parent, returns the parent node id or id if there is no
    /// parent.
    /// This function returns the immediate parent in the AST, whereas get_parent
    /// returns the enclosing item.
```
One would think that one can walk up the tree by repeatedly calling `get_parent_node` until it returns the argument, and then work on the `NodeId`s that arise. However, that is not true: `get_parent_node` will return id 0 (the crate itself) for items that sit directly in the crate; calling `get` on that `NodeId` will panic.

So, the fact that `get_parent_node` returns the root when passed the root is actually not really useful, because the root itself is already a somewhat degenerate node. This improves the doc so hopefully people writing code that "walks up the tree" don't run into this issue like I did...

1 files changed, 4 insertions, 2 deletions

diff --git a/src/librustc/hir/map/mod.rs b/src/librustc/hir/map/mod.rs
index 3fdd9c34f46..45b1d6c1841 100644
--- a/src/librustc/hir/map/mod.rs
+++ b/src/librustc/hir/map/mod.rs
@@ -553,7 +553,9 @@ impl<'hir> Map<'hir> {
     }
 
     /// Similar to get_parent, returns the parent node id or id if there is no
-    /// parent.
+    /// parent. Note that the parent may be CRATE_NODE_ID, which is not itself
+    /// present in the map -- so passing the return value of get_parent_node to
+    /// get may actually panic.
     /// This function returns the immediate parent in the AST, whereas get_parent
     /// returns the enclosing item. Note that this might not be the actual parent
     /// node in the AST - some kinds of nodes are not in the map and these will
@@ -629,7 +631,7 @@ impl<'hir> Map<'hir> {
     }
 
     /// Retrieve the NodeId for `id`'s enclosing method, unless there's a
-    /// `while` or `loop` before reacing it, as block tail returns are not
+    /// `while` or `loop` before reaching it, as block tail returns are not
     /// available in them.
     ///
     /// ```