docs: extend Javadoc #90
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
|
There was a problem hiding this comment. See #85; for external users this method effectively did not exist before. This assumes the next version will be 0.25.1 |
||
| */ | ||
| @SuppressWarnings("SameParameterValue") | ||
| public static @NonNull InputEncoding valueOf(@NonNull Charset charset) throws IllegalArgumentException { | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
Comment on lines
+405
to
+406
There was a problem hiding this comment. I hope I understood the logic in https://github.com/tree-sitter/tree-sitter/blob/37a9ecd5b7d52786d0673611f0b8fc54292b1ac1/lib/src/parser.c#L1553 correctly, and That is probably worth documenting, otherwise users might be unsure how this There was a problem hiding this comment. But that It seems even Maybe that should be >= instead of <= to cancel as soon as 1000 or more bytes were consumed? Or is the intention here to additionally verify that the parser consumes the bytes in pieces and not all the 1024 bytes at once?
There was a problem hiding this comment.
That is what I assumed. 💀 |
||
| */ | ||
| public Options(Predicate<State> progressCallback) { | ||
| this.progressCallback = progressCallback; | ||
| } | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 {@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 {@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. Return {@code true} to cancel query execution, | ||
| * {@code false} to continue query execution. | ||
|
Comment on lines
+296
to
+297
There was a problem hiding this comment. Same as the comment in |
||
| * @param predicateCallback Custom predicate handler. | ||
| */ | ||
| private Options( | ||
|
|
@@ -304,7 +305,8 @@ private Options( | |
| } | ||
|
|
||
| /** | ||
| * @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; | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems superfluous. Just click the badge.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My idea here was to make it a bit easier for users to discover.
Otherwise new users might not know how to get started with this project, and might not consider looking at the Javadoc (in case they do notice the badge). They might not expect such an extensive usage example in the package Javadoc because not all projects have that (respectively have it in separate documentation or in the README).