diff --git a/README.md b/README.md index 95ccc0a..4d2cb3d 100644 --- a/README.md +++ b/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/ diff --git a/src/main/java/io/github/treesitter/jtreesitter/InputEncoding.java b/src/main/java/io/github/treesitter/jtreesitter/InputEncoding.java index 9ce00b0..df88380 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/InputEncoding.java +++ b/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 { diff --git a/src/main/java/io/github/treesitter/jtreesitter/Language.java b/src/main/java/io/github/treesitter/jtreesitter/Language.java index efc0272..9475038 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/Language.java +++ b/src/main/java/io/github/treesitter/jtreesitter/Language.java @@ -67,6 +67,7 @@ private static UnsatisfiedLinkError unresolved(String name) { * The {@linkplain Arena} used to load the language * must not be closed while the language is being used. * + * @throws UnsatisfiedLinkError If the language symbol could not be found. * @throws RuntimeException If the language could not be loaded. * @since 0.23.1 */ diff --git a/src/main/java/io/github/treesitter/jtreesitter/LookaheadIterator.java b/src/main/java/io/github/treesitter/jtreesitter/LookaheadIterator.java index 4f712f4..d891a3c 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/LookaheadIterator.java +++ b/src/main/java/io/github/treesitter/jtreesitter/LookaheadIterator.java @@ -17,6 +17,8 @@ *

Lookahead iterators can be useful to generate suggestions and improve syntax error diagnostics.
* To get symbols valid in an {@index ERROR} node, use the lookahead iterator on its first leaf node state.
* 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 { diff --git a/src/main/java/io/github/treesitter/jtreesitter/Parser.java b/src/main/java/io/github/treesitter/jtreesitter/Parser.java index feb9eb2..5b03d45 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/Parser.java +++ b/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 progressCallback; + /** + * @param progressCallback Called when parsing progress was made. Return {@code true} to cancel parsing, + * {@code false} to continue parsing. + */ public Options(Predicate progressCallback) { this.progressCallback = progressCallback; } diff --git a/src/main/java/io/github/treesitter/jtreesitter/QueryCursor.java b/src/main/java/io/github/treesitter/jtreesitter/QueryCursor.java index 2e2b2e1..91b8223 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/QueryCursor.java +++ b/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 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 progressCallback) { this.progressCallback = progressCallback; diff --git a/src/main/java/io/github/treesitter/jtreesitter/QueryMatch.java b/src/main/java/io/github/treesitter/jtreesitter/QueryMatch.java index 4a14e86..2dca95b 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/QueryMatch.java +++ b/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 captures) { /** Creates an instance of a QueryMatch record class. */ diff --git a/src/main/java/io/github/treesitter/jtreesitter/TreeCursor.java b/src/main/java/io/github/treesitter/jtreesitter/TreeCursor.java index 8929555..8cd2123 100644 --- a/src/main/java/io/github/treesitter/jtreesitter/TreeCursor.java +++ b/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 {