From a79d2364e72aaaded0d980ae3be8bacc3458352d Mon Sep 17 00:00:00 2001
From: Arthur Milchior <arthur@milchior.fr>
Date: Sat, 27 Jan 2024 21:42:06 +0100
Subject: [PATCH] Clarify debugging graph dependency (#1862)

---
 src/incrcomp-debugging.md | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/src/incrcomp-debugging.md b/src/incrcomp-debugging.md
index 3606943dd..8af06310c 100644
--- a/src/incrcomp-debugging.md
+++ b/src/incrcomp-debugging.md
@@ -2,13 +2,16 @@
 
 ## Testing the dependency graph
 
-There are various ways to write tests against the dependency graph.
-The simplest mechanisms are the `#[rustc_if_this_changed]` and
-`#[rustc_then_this_would_need]` annotations. These are used in ui tests
-to test whether the expected set of paths exist in the dependency graph.
-As an example, see `tests/ui/dep-graph/dep-graph-caller-callee.rs`.
+There are various ways to write tests against the dependency graph.  The
+simplest mechanisms are the `#[rustc_if_this_changed]` and
+`#[rustc_then_this_would_need]` annotations. These are used in [ui] tests to test
+whether the expected set of paths exist in the dependency graph.
 
-The idea is that you can annotate a test like:
+[`tests/ui/dep-graph/dep-graph-caller-callee.rs`]: /~https://github.com/rust-lang/rust/blob/master/tests/ui/dep-graph/dep-graph-caller-callee.rs
+[ui]: tests/ui.html
+
+As an example, see [`tests/ui/dep-graph/dep-graph-caller-callee.rs`], or the
+tests below.
 
 ```rust,ignore
 #[rustc_if_this_changed]
@@ -16,16 +19,24 @@ fn foo() { }
 
 #[rustc_then_this_would_need(TypeckTables)] //~ ERROR OK
 fn bar() { foo(); }
+```
+
+This should be read as
+> If this (`foo`) is changed, then this (i.e. `bar`)'s TypeckTables would need
+  to be changed. Also, this
 
+You could also add the lines
+
+```rust,ignore
 #[rustc_then_this_would_need(TypeckTables)] //~ ERROR no path
 fn baz() { }
 ```
 
-This will check whether there is a path in the dependency graph from `Hir(foo)`
-to `TypeckTables(bar)`. An error is reported for each
-`#[rustc_then_this_would_need]` annotation that indicates whether a path
-exists. `//~ ERROR` annotations can then be used to test if a path is found (as
-demonstrated above).
+Whose meaning is
+> If `foo` is changed, then `baz`'s TypeckTables does not need to be changed, as there is no path.
+
+Recall that the `//~ ERROR OK` is a comment from the point of view of the Rust
+code we test, but is meaningful from the point of view of the test itself.
 
 ## Debugging the dependency graph