diff --git a/cranelift/codegen/meta-python/base/instructions.py b/cranelift/codegen/meta-python/base/instructions.py
index 53d1586abf..ebb7257f65 100644
--- a/cranelift/codegen/meta-python/base/instructions.py
+++ b/cranelift/codegen/meta-python/base/instructions.py
@@ -143,6 +143,12 @@ br_table = Instruction(
 
         Note that this branch instruction can't pass arguments to the targeted
         blocks. Split critical edges as needed to work around this.
+
+        Do not confuse this with "tables" in WebAssembly. ``br_table`` is for
+        jump tables with destinations within the current function only -- think
+        of a ``match`` in Rust or a ``switch`` in C.  If you want to call a
+        function in a dynamic library, that will typically use
+        ``call_indirect``.
         """,
         ins=(x, EBB, JT), is_branch=True, is_terminator=True)