docs: extend Javadoc (#90)

and remove a reference to the archived android-tree-sitter

Author: Marcono1234

README.md

@@ -26,7 +26,6 @@ These alternatives support older JDK versions or Android:
 - [tree-sitter/kotlin-tree-sitter](https://github.com/tree-sitter/kotlin-tree-sitter) (JDK 17+, Android SDK 23+, Kotlin 1.9)
 - [bonede/tree-sitter-ng](https://github.com/bonede/tree-sitter-ng) (JDK 8+)
 - [seart-group/java-tree-sitter](https://github.com/seart-group/java-tree-sitter) (JDK 11+)
-- [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

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

@@ -17,6 +17,8 @@
  * <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.
+ *
+ * @see Language#lookaheadIterator(short)
  */
 @NullMarked
 public final class LookaheadIterator implements AutoCloseable, Iterator<LookaheadIterator.Symbol> {

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

@@ -102,7 +102,7 @@ public QueryCursor setMaxStartDepth(@Unsigned int maxStartDepth) {
      * than the specified range, but part of that node intersects with the range,
      * the entire match will be returned.
      *
-     * @throws IllegalArgumentException If `endByte > startByte`.
+     * @throws IllegalArgumentException If {@code endByte > startByte}.
      */
     public QueryCursor setByteRange(@Unsigned int startByte, @Unsigned int endByte) throws IllegalArgumentException {
         if (!ts_query_cursor_set_byte_range(self, startByte, endByte)) {
@@ -123,7 +123,7 @@ public QueryCursor setByteRange(@Unsigned int startByte, @Unsigned int endByte)
      * than the specified range, but part of that node intersects with the range,
      * the entire match will be returned.
      *
-     * @throws IllegalArgumentException If `endPoint > startPoint`.
+     * @throws IllegalArgumentException If {@code endPoint > startPoint}.
      */
     public QueryCursor setPointRange(Point startPoint, Point endPoint) throws IllegalArgumentException {
         try (var alloc = Arena.ofConfined()) {
@@ -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

@@ -14,6 +14,9 @@
  *
  * @apiNote The node the cursor was constructed with is considered the
  * root of the cursor, and the cursor cannot walk outside this node.
+ *
+ * @see Tree#walk()
+ * @see Node#walk()
  */
 @NullMarked
 public final class TreeCursor implements AutoCloseable, Cloneable {