From 8b3ee230d931e5e189fe654f8f5829b7d471de6a Mon Sep 17 00:00:00 2001
From: Arthur Milchior <arthur@milchior.fr>
Date: Sat, 27 Jan 2024 20:27:37 +0100
Subject: [PATCH 1/2] Clarify debugging graph dependency

I found the explanation very confusing. I tried to take the same test and give more details, so that the next reader could understand this part of the test even if they are not that used to macros.

I also added a link to the example file mentionned
---
 src/incrcomp-debugging.md | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/src/incrcomp-debugging.md b/src/incrcomp-debugging.md
index 3606943dd..f1c89fd8f 100644
--- a/src/incrcomp-debugging.md
+++ b/src/incrcomp-debugging.md
@@ -2,13 +2,15 @@
 
 ## 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
+
+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 +18,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
 

From 67d264f40b6c840aae6502d5ad4f5b68d7d1a299 Mon Sep 17 00:00:00 2001
From: Arthur Milchior <arthur@milchior.fr>
Date: Sat, 27 Jan 2024 21:09:34 +0100
Subject: [PATCH 2/2] [iOS] add link to UI

---
 src/incrcomp-debugging.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/incrcomp-debugging.md b/src/incrcomp-debugging.md
index f1c89fd8f..8af06310c 100644
--- a/src/incrcomp-debugging.md
+++ b/src/incrcomp-debugging.md
@@ -4,10 +4,11 @@
 
 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
+`#[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.
 
 [`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.