diff options
author | Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com> | 2024-03-25 18:18:28 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-03-25 16:18:28 +0100 |
commit | 8e59a7ba88776d5425bafc6eefd978de3312fcdf (patch) | |
tree | 3fb25661f414faf3bb70f9b24e31b82260287ca5 /runtime/syntax/testdir/input | |
parent | 4b715bdaf4ca08ba0f64475e250c0fe799ab6d9b (diff) |
runtime(java): Recognise the inline kind of the {@return} tag (#14284)
Also:
- Refine comment matching (javaComment{Error\ and,Start}).
- Continue rewriting regexps (prefer atom grouping with
non-capturing parens; factor out common prefixes in
alternations).
- Allow for relative paths with the _file_ attribute of
{@snippet}.
- Anticipate HTML in the @see tags.
- Match the nullary method parens in javaDocSeeTagParam.
- Improve the boundary patterns for summary sentences of
documentation.
> This sentence ends at ... or at the first tag (as defined
> below).
There are Java documentation tags (@) and there are HTML
tags (<?>) (with Markdown looming large; see JEP 467). With
block tags, e.g. @param, @return, @see, we begin another
documentation "sentence" whether or not the author has
terminated the summary sentence with a period; with
.<!-- -->, we may follow abbreviations, enumerations,
initials, (but instead consider @literal or ) _within_
the summary sentence. On the other hand, inline tags, e.g.
@code, @link, @literal, should not terminate the summary
sentence.
References:
https://bugs.openjdk.org/browse/JDK-8075778
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#firstsentence
https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html
Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
Diffstat (limited to 'runtime/syntax/testdir/input')
-rw-r--r-- | runtime/syntax/testdir/input/java_comments.java | 85 |
1 files changed, 75 insertions, 10 deletions
diff --git a/runtime/syntax/testdir/input/java_comments.java b/runtime/syntax/testdir/input/java_comments.java index be347d7eb5..3c1a8a2e32 100644 --- a/runtime/syntax/testdir/input/java_comments.java +++ b/runtime/syntax/testdir/input/java_comments.java @@ -1,11 +1,68 @@ -// VIM_TEST_SETUP unlet! g:java_ignore_javadoc g:java_no_trail_space_error -// VIM_TEST_SETUP unlet! g:java_no_tab_space_error +// VIM_TEST_SETUP unlet! g:java_ignore_javadoc g:java_no_trail_space_error +// VIM_TEST_SETUP unlet! g:java_no_tab_space_error // VIM_TEST_SETUP let [g:java_space_errors,g:java_comment_strings] = [1,1] -// VIM_TEST_SETUP setlocal spell +// VIM_TEST_SETUP setlocal spell | highlight link javaCommentStart Todo + + + + +/**/ /*/ */ /* /*/ /*/*/ /*//*/ /** Comment tests. + * <p>There is no entry point method {@code main}: + * {@snippet file = Snippets.java region = main id = _01} + * <p>There is no textual representation: + * {@snippet class = Snippets region = toString id = _02} */ class CommentsTests -{ /* TRAILING BLANKS AND MESSPILLINGS ARE SIGNIFICANT! */ - /** - * The method {@code main} must be declared {@code public}, {@code +{ + /** No-op, i. e. no operation. + * ({@literal@literal} may be used with {@code .} for contraction.) + * @return {@code null} */ + Void noOp1() { return null; } + + /** No-op, i.e. no operation. + * ({@literal<!-- -->} may be used after {@code .} for contraction.) + * @return {@code null} */ + Void noOp2() { return null; } + + /** No-op, i.e\u002e no operation. + * ({@literal\u005cu002e} is processed early, use alternatives.) + * @return {@code null} */ + Void noOp3() { return null; } + + /** No-op, i.e{@literal .} no operation. + * @return {@code null} */ + Void noOp4() { return null; } + + /** No-op, i.e.<!-- --> no operation. + * @return {@code null} */ + Void noOp5() { return null; } + + /** No-op, i.e. no operation. + * @return {@code null} */ + Void noOp6() { return null; } + + /** {@return {@code null}, with no-op, i.e. no operation} */ + Void noOp7() { return null; } + + /** {@return {@code null}, with no-op, i.e. no operation}.. */ + Void noOp8() { return null; } + + /** {@return {@code null}, with no-op, i.e. no operation} . . */ + Void noOp9() { return null; } + + /** Returns an empty string for an @Override annotated method + * (see Chapter 9.6.4.4 {@literal @Override} in a Java Language + * Specification) overridden from <code>java.lang.Object</code> + * + * @return an empty string */// No period for the above summary! + @Override public String toString() { return ""; } +} + +// javadoc --snippet-path . --source-path . -d /tmp/doc/ -package \ +// -tag 'jls:a:See Java Language Specification:' Snippets.java +/** Snippets for comment tests. */ +class Snippets +{ /* TRAILING BLANKS AND MESSPILLINGS ARE SIGNIFICANT! */ + /** The method {@code main} must be declared {@code public}, {@code * static}, and {@code void}. It must specify a formal parameter * whose declared type is array of {@link String}. Therefore, * either of the following declarations is acceptable: @@ -16,10 +73,18 @@ class CommentsTests *{@code public static void main(String... args) { }}</pre> * * @param args optional commande-line arguments - * @jls 12.1.4 Invoke {@code Test.main} - */ - // @start region = main + * @jls 12.1.4 Invoke {@code Test.main} */ + // @start region = main // @link substring = 'String' target = 'java.lang.String' : public static void main(String[] args) { } - // @end + // @end + + /** {@return an empty string} + * @see <a href="https://docs.oracle.com/javase/specs/jls/se21/html/jls-3.html#jls-3.10.5">3.10.5 String Literals</a> + * @see Object#toString() */ + // @start region = toString + // @replace substring = '""' replacement = "\u0022\u0022" + // @link regex = '\bString' target = java.lang.String type = linkplain : + @Override public String toString() { return ""; } + // @end } |