[Docs] Add some comments on type updating in various places (#4548)

2 files changed, 30 insertions, 7 deletions

diff --git a/src/ir/type-updating.h b/src/ir/type-updating.h
index 151b0d41a..85134da67 100644
--- a/src/ir/type-updating.h
+++ b/src/ir/type-updating.h
@@ -23,13 +23,30 @@
 
 namespace wasm {
 
-// a class that tracks type dependencies between nodes, letting you
-// update types efficiently when removing and altering code.
-// altering code can alter types in the following way:
-//   * removing a break can make a block unreachable, if nothing else
-//     reaches it
-//   * altering the type of a child to unreachable can make the parent
-//     unreachable
+//
+// A class that tracks type dependencies between nodes, letting you update types
+// efficiently when removing and altering code incrementally.
+//
+// Altering code can alter types beyond the current node in the following ways:
+//
+//  1. Removing a break can make a block unreachable, if nothing else reaches
+//     it.
+//  2. Altering the type of a child to unreachable can make the parent
+//     unreachable.
+//
+// Most passes don't do either of the above and can just do replaceCurrent when
+// replacing one thing with another, which is fine as no types need to be
+// updated outside of the item being replaced. Passes that do one of the two
+// things mentioned need to update types in the IR affected by the change (which
+// can include any of the parent nodes, in general) and they have two main ways
+// to do so:
+//
+//  * Call ReFinalize() after making all their changes. The IR will be in an
+//    invalid state while making the changes, and only fixed up at the end by
+//    ReFinalize(), but often that is good enough.
+//  * Use this class, TypeUpdater. This lets you update the IR after each
+//    incremental change that you perform, keeping the IR valid constantly.
+//
 struct TypeUpdater
   : public ExpressionStackWalker<TypeUpdater,
                                  UnifiedExpressionVisitor<TypeUpdater>> {
diff --git a/src/passes/param-utils.h b/src/passes/param-utils.h
index 10645b230..202c8b007 100644
--- a/src/passes/param-utils.h
+++ b/src/passes/param-utils.h
@@ -58,6 +58,12 @@ std::unordered_set<Index> getUsedParams(Function* func);
 // use cases are either to send a single function, or to send a set of functions
 // that all have the same heap type (and so if they all do not use some
 // parameter, it can be removed from them all).
+//
+// This does *not* update the types in call_refs. It is assumed that the caller
+// will be updating types, which is simpler as there may be other locations that
+// need adjusting and it is easier to do it all in one place. Also, the caller
+// can update all the types at once throughout the program after making
+// multiple calls to removeParameter().
 bool removeParameter(const std::vector<Function*>& funcs,
                      Index index,
                      const std::vector<Call*>& calls,