Improve documentation for binding-graph wit component

crates/codegen/runtime/cargo/wasm/src/runtime/interface/bindings.wit.jinja2

@@ -3,6 +3,9 @@ interface bindings {
 
     /// A giant graph that contains name binding information for all source files within the compilation unit.
     /// It stores cursors to all definitions and references, and can resolve the edges between them.
+    /// Most cursors pointing to identifier terminals will resolve to either a definition or a reference. For example, in `contract A is B {}` the cursor to identifier `A` will resolve to a definition, and the cursor to identifier `B` will resolve to a reference.
+    /// There is one specific case in which a cursor to an identifier resolves to both: a non-aliased symbol import `import {X} from "library"`, where the identifier `X` is both a definition and a reference (to the symbol exported from `"library"`).
+    /// Also, an identifier denoting a feature in a `pragma experimental` directive will not resolve to either.
     resource binding-graph {
         /// Tries to resolve the identifier terminal pointed at by the provided cursor to a definition.
         /// If successful, returns the definition. Otherwise, returns `undefined`.
@@ -32,7 +35,7 @@ interface bindings {
         /// For `contract X {}`, that is the location of the parent `ContractDefinition` node.
         definiens-location: func() -> binding-location;
 
-        /// Returns a list of all references this definition binds to.
+        /// Returns a list of all references that bind to this definition.
         references: func() -> list<reference>;
     }