From 400e658e0d32ff4654e0097d678d257c802f23bc Mon Sep 17 00:00:00 2001
From: Fons van der Plas <fonsvdplas@gmail.com>
Date: Tue, 16 Jan 2024 17:56:46 +0100
Subject: [PATCH] docs

---
 src/Topology.jl       | 15 ++++++++++++++-
 src/TopologyUpdate.jl |  9 ++++++---
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/Topology.jl b/src/Topology.jl
index 766e751..5cab523 100644
--- a/src/Topology.jl
+++ b/src/Topology.jl
@@ -24,7 +24,20 @@ function ExprAnalysisCache(old_cache::ExprAnalysisCache; new_properties...)
     ExprAnalysisCache(;properties...)
 end
 
-"The (information needed to create the) dependency graph of a notebook. Cells are linked by the names of globals that they define and reference. 🕸"
+"""
+The (information needed to create the) dependency graph of a notebook. Cells are linked by the names of globals that they define and reference. 🕸
+
+`NotebookTopology` is an immutable structure. In Pluto's case, where the notebook is constantly changing (being edited), it functions as a *snapshot* of the notebook's reactive state at a current time.
+
+This also means that the `NotebookTopology` cannot be mutated to reflect changes in the notebook. This is done by the `update_topology` function, which takes an old topology and calculates the next one.
+
+# Fields
+- `nodes` is really the **dependency graph**. For each cell, it stores the dependency links.
+- `codes` is a snapshot of the cell codes at the time when the `topology` was calculated, including some metadata that is used by Pluto.
+- `cell_order` is a snapshot of the cell order at the time when the `topology` was calculated.
+- `unresolved_cells` contains cells that still have unresolved macro calls
+- `disabled_cells` contains cells that are disabled (used by Pluto)
+"""
 Base.@kwdef struct NotebookTopology{C <: AbstractCell}
     nodes::ImmutableDefaultDict{C,ReactiveNode}=ImmutableDefaultDict{C,ReactiveNode}(ReactiveNode)
     codes::ImmutableDefaultDict{C,ExprAnalysisCache}=ImmutableDefaultDict{C,ExprAnalysisCache}(ExprAnalysisCache)
diff --git a/src/TopologyUpdate.jl b/src/TopologyUpdate.jl
index 24e70e6..2f6c77f 100644
--- a/src/TopologyUpdate.jl
+++ b/src/TopologyUpdate.jl
@@ -6,7 +6,10 @@ import ExpressionExplorer: SymbolsState, FunctionNameSignaturePair
 """
 ```julia
 function updated_topology(
-	old_topology::NotebookTopology{C}, notebook_cells::Iterable{C}, updated_cells::Iterable{C}; 
+	old_topology::NotebookTopology{C}, 
+	notebook_cells::Iterable{C}, 
+	updated_cells::Iterable{C}; 
+
 	get_code_str::Function, 
 	get_code_expr::Function, 
 	get_cell_disabled::Function=c->false,
@@ -15,9 +18,9 @@ function updated_topology(
 
 Return a copy of `old_topology`, but with new reactivity information from `updated_cells` taken into account. This function is used when cell code changes.
 
-`notebook_cells` should contain all cells in the reactive document.
+`notebook_cells` should contain all cells in the reactive document. `updated_cells` contains the cells that changed (e.g. because they were edited).
 
-The functions `get_code_str` and `get_code_expr` should return the code string and parsed expression for a given cell. `get_cell_disabled` should return `true` if a cell is disabled, defaults to `false`.
+The functions `get_code_str` and `get_code_expr` should return the code string and parsed expression for a given cell. `get_cell_disabled` should return `true` if a cell is disabled, defaults to `false`. 
 """
 function updated_topology(
 	old_topology::NotebookTopology{C}, notebook_cells, updated_cells;