feat(web): document the API

lib/binding_web/src/tree.ts

@@ -5,6 +5,7 @@ import { TreeCursor } from './tree_cursor';
 import { marshalEdit, marshalPoint, unmarshalNode, unmarshalRange } from './marshal';
 import { TRANSFER_BUFFER } from './parser';
 
+/** @internal */
 export function getText(tree: Tree, startIndex: number, endIndex: number, startPosition: Point): string {
   const length = endIndex - startIndex;
   let result = tree.textCallback(startIndex, startPosition);
@@ -26,13 +27,18 @@ export function getText(tree: Tree, startIndex: number, endIndex: number, startP
   return result ?? '';
 }
 
+/** A tree that represents the syntactic structure of a source code file. */
 export class Tree {
   /** @internal */
   private [0] = 0; // Internal handle for WASM
 
+  /** @internal */
   textCallback: ParseCallback;
+
+  /** The language that was used to parse the syntax tree. */
   language: Language;
 
+  /** @internal */
   constructor(internal: Internal, address: number, language: Language, textCallback: ParseCallback) {
     assertInternal(internal);
     this[0] = address;
@@ -40,26 +46,28 @@ export class Tree {
     this.textCallback = textCallback;
   }
 
+  /** Create a shallow copy of the syntax tree. This is very fast. */
   copy(): Tree {
     const address = C._ts_tree_copy(this[0]);
     return new Tree(INTERNAL, address, this.language, this.textCallback);
   }
 
+  /** Delete the syntax tree, freeing its resources. */
   delete(): void {
     C._ts_tree_delete(this[0]);
     this[0] = 0;
   }
 
-  edit(edit: Edit): void {
-    marshalEdit(edit);
-    C._ts_tree_edit_wasm(this[0]);
-  }
-
+  /** Get the root node of the syntax tree. */
   get rootNode(): Node {
     C._ts_tree_root_node_wasm(this[0]);
     return unmarshalNode(this)!;
   }
 
+  /**
+   * Get the root node of the syntax tree, but with its position shifted
+   * forward by the given offset.
+   */
   rootNodeWithOffset(offsetBytes: number, offsetExtent: Point): Node {
     const address = TRANSFER_BUFFER + SIZE_OF_NODE;
     C.setValue(address, offsetBytes, 'i32');
@@ -68,14 +76,34 @@ export class Tree {
     return unmarshalNode(this)!;
   }
 
-  getLanguage(): Language {
-    return this.language;
+  /**
+   * Edit the syntax tree to keep it in sync with source code that has been
+   * edited.
+   *
+   * You must describe the edit both in terms of byte offsets and in terms of
+   * row/column coordinates.
+   */
+  edit(edit: Edit): void {
+    marshalEdit(edit);
+    C._ts_tree_edit_wasm(this[0]);
   }
 
+  /** Create a new {@link TreeCursor} starting from the root of the tree. */
   walk(): TreeCursor {
     return this.rootNode.walk();
   }
 
+  /**
+   * Compare this old edited syntax tree to a new syntax tree representing
+   * the same document, returning a sequence of ranges whose syntactic
+   * structure has changed.
+   *
+   * For this to work correctly, this syntax tree must have been edited such
+   * that its ranges match up to the new tree. Generally, you'll want to
+   * call this method right after calling one of the [`Parser::parse`]
+   * functions. Call it on the old tree that was passed to parse, and
+   * pass the new tree that was returned from `parse`.
+   */
   getChangedRanges(other: Tree): Range[] {
     if (!(other instanceof Tree)) {
       throw new TypeError('Argument must be a Tree');
@@ -97,6 +125,7 @@ export class Tree {
     return result;
   }
 
+  /** Get the included ranges that were used to parse the syntax tree. */
   getIncludedRanges(): Range[] {
     C._ts_tree_included_ranges_wasm(this[0]);
     const count = C.getValue(TRANSFER_BUFFER, 'i32');