docs: extend Javadoc

Author: Marcono1234

README.md

@@ -1,11 +1,15 @@
 # Java Tree-sitter
 
-[![CI][ci]](https://github.com/tree-sitter/java-tree-sitter/actions/workflows/ci.yml)
-[![central][central]](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter)
-[![docs][docs]](https://tree-sitter.github.io/java-tree-sitter/)
+[![CI][ci-shield]](https://github.com/tree-sitter/java-tree-sitter/actions/workflows/ci.yml)
+[![central][central-shield]](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter)
+[![docs][docs-shield]][docs]
 
 Java bindings to the [tree-sitter] parsing library.
 
+## Usage
+
+See the [documentation][docs].
+
 ## Building
 
 - Install JDK 22 and set `JAVA_HOME` to it
@@ -29,8 +33,9 @@ These alternatives support older JDK versions or Android:
 - [AndroidIDEOfficial/android-tree-sitter](https://github.com/AndroidIDEOfficial/android-tree-sitter) (Android SDK 21+)
 
 [tree-sitter]: https://tree-sitter.github.io/tree-sitter/
-[ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/java-tree-sitter/ci.yml?logo=github&label=CI
-[central]: https://img.shields.io/maven-central/v/io.github.tree-sitter/jtreesitter?logo=sonatype&label=Maven%20Central
-[docs]: https://img.shields.io/github/deployments/tree-sitter/java-tree-sitter/github-pages?logo=githubpages&label=API%20Docs
+[ci-shield]: https://img.shields.io/github/actions/workflow/status/tree-sitter/java-tree-sitter/ci.yml?logo=github&label=CI
+[central-shield]: https://img.shields.io/maven-central/v/io.github.tree-sitter/jtreesitter?logo=sonatype&label=Maven%20Central
+[docs-shield]: https://img.shields.io/github/deployments/tree-sitter/java-tree-sitter/github-pages?logo=githubpages&label=API%20Docs
+[docs]: https://tree-sitter.github.io/java-tree-sitter/
 [FFM]: https://docs.oracle.com/en/java/javase/22/core/foreign-function-and-memory-api.html
 [jextract]: https://jdk.java.net/jextract/

src/main/java/io/github/treesitter/jtreesitter/InputEncoding.java

@@ -40,6 +40,7 @@ Charset charset() {
      * @param charset one of {@link StandardCharsets#UTF_8}, {@link StandardCharsets#UTF_16BE},
      *                {@link StandardCharsets#UTF_16LE}, or {@link StandardCharsets#UTF_16} (native byte order).
      * @throws IllegalArgumentException If the character set is invalid.
+     * @since 0.25.1
      */
     @SuppressWarnings("SameParameterValue")
     public static @NonNull InputEncoding valueOf(@NonNull Charset charset) throws IllegalArgumentException {

src/main/java/io/github/treesitter/jtreesitter/Language.java

@@ -67,6 +67,7 @@ private static UnsatisfiedLinkError unresolved(String name) {
      * <strong>The {@linkplain Arena} used to load the language
      * must not be closed while the language is being used.</strong>
      *
+     * @throws UnsatisfiedLinkError If the language symbol could not be found.
      * @throws RuntimeException If the language could not be loaded.
      * @since 0.23.1
      */

src/main/java/io/github/treesitter/jtreesitter/LookaheadIterator.java

@@ -14,6 +14,8 @@
 /**
  * A class that is used to look up valid symbols in a specific parse state.
  *
+ * <p>Iterator instances can be created using {@link Language#lookaheadIterator(short)}.
+ *
  * <p>Lookahead iterators can be useful to generate suggestions and improve syntax error diagnostics.<br>
  * To get symbols  valid in an {@index ERROR} node, use the lookahead iterator on its first leaf node state.<br>
  * For {@index MISSING} nodes, a lookahead iterator created on the previous non-extra leaf node may be appropriate.

src/main/java/io/github/treesitter/jtreesitter/Parser.java

@@ -26,6 +26,7 @@ public final class Parser implements AutoCloseable {
      * Creates a new instance with a {@code null} language.
      *
      * @apiNote Parsing cannot be performed while the language is {@code null}.
+     * @see #setLanguage(Language)
      */
     public Parser() {
         arena = Arena.ofShared();
@@ -400,6 +401,10 @@ public String toString() {
     public static final class Options {
         private final Predicate<State> progressCallback;
 
+        /**
+         * @param progressCallback Called when parsing progress was made. Return {@code true} to cancel parsing,
+         *                         {@code false} to continue parsing.
+         */
         public Options(Predicate<State> progressCallback) {
             this.progressCallback = progressCallback;
         }

src/main/java/io/github/treesitter/jtreesitter/QueryCursor.java

@@ -293,7 +293,8 @@ public static class Options {
         private final @Nullable BiPredicate<QueryPredicate, QueryMatch> predicateCallback;
 
         /**
-         * @param progressCallback Progress handler.
+         * @param progressCallback Progress handler. Return {@code true} to cancel query execution,
+         *                         {@code false} to continue query execution.
          * @param predicateCallback Custom predicate handler.
          */
         private Options(
@@ -304,7 +305,8 @@ private Options(
         }
 
         /**
-         * @param progressCallback Progress handler.
+         * @param progressCallback Progress handler. Return {@code true} to cancel query execution,
+         *                         {@code false} to continue query execution.
          */
         public Options(Predicate<State> progressCallback) {
             this.progressCallback = progressCallback;

src/main/java/io/github/treesitter/jtreesitter/QueryMatch.java

@@ -7,7 +7,7 @@
 import java.util.List;
 import org.jspecify.annotations.NullMarked;
 
-/** A match that corresponds to a certain pattern in the query. */
+/** A match that corresponds to a certain pattern in a {@link Query}. */
 @NullMarked
 public record QueryMatch(@Unsigned int patternIndex, List<QueryCapture> captures) {
     /** Creates an instance of a QueryMatch record class. */

src/main/java/io/github/treesitter/jtreesitter/TreeCursor.java

@@ -12,6 +12,8 @@
 /**
  * A class that can be used to efficiently walk a {@linkplain Tree syntax tree}.
  *
+ * <p>A cursor can be created using {@link Tree#walk()} and {@link Node#walk()}.
+ *
  * @apiNote The node the cursor was constructed with is considered the
  * root of the cursor, and the cursor cannot walk outside this node.
  */