Issue #9745: Added JavadocMethod inline return tag support #16605

kkoutsilis · 2025-03-18T22:12:14Z

Aims to close #9745
Added new allowInlineReturn property in JavadocMethodCheck to control whether to allow inline return tags in javadoc.
Default. value is false to not break compatibility

romani · 2025-03-19T01:29:16Z

@kkoutsilis , I am glad you are back.

kkoutsilis · 2025-03-19T06:57:43Z

@kkoutsilis , I am glad you are back.

Thanks @romani.
FYI I realized that the regex will also match {@see ...} which should not be the case. Trying to fix this

Update
I don't see any tests or checks for @see tag, do we care about it here?

romani · 2025-03-22T13:24:57Z

JavadocMethodCheck is not AST based, so robust implementation is unlikely possible to make.
We are ok with this.

All such checks are waiting for complete reimplementation to use AST.

So please find some good middle, where Check is doing validadtion but does not produce false-positives, and we will merge it. Users very angry on false-positives, but ok with false-negatives, as it does not block builds.

kkoutsilis · 2025-03-24T20:34:39Z

Hey @romani, CI is green apart from ci/circleci: no-error-xwiki, but I see this issue exists in the main pipeline. I believe this PR can be reviewed. What do you think?

romani · 2025-03-24T20:47:04Z

Xwiki is not related.

Please trigger diff report for JavadocMethod

kkoutsilis · 2025-03-24T20:49:31Z

Github, generate report for JavadocMethod

github-actions · 2025-03-24T20:50:43Z

Failed to download or process the specified configuration(s).
Error details:

Please ensure you've used one of the following commands correctly:

'GitHub, generate report for <config_bundle_path>'
'GitHub, generate report by config from <file_path>'
'GitHub, generate report for configs in PR description'

And check that all specified configs or files exist and are valid.

Link: https://github.com/checkstyle/checkstyle/actions/runs/14045616016

romani · 2025-03-24T20:51:26Z

https://github.com/checkstyle/checkstyle/tree/master/.github/workflows#diff-report-by-configuration-at-test-configs-repository

You missed subfolder.

kkoutsilis · 2025-03-24T21:02:49Z

Github, generate report for JavadocMethod/all-examples-in-one

github-actions · 2025-03-24T21:49:32Z

Report for JavadocMethod/all-examples-in-one:
https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4023370ae179fafcb186f4846342cfd7dc964da1_2025214919/reports/diff/index.html

rdiachenko · 2025-03-25T21:07:05Z

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java

@@ -256,13 +261,21 @@ public class JavadocMethodCheck extends AbstractCheck {
    /** Compiled regexp to match Javadoc tags with no argument. */
    private static final Pattern MATCH_JAVADOC_NOARG =
            CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s+\\S");
+    /** Compiled regexp to match Javadoc tags with no argument allowing inline return tag. */
+    private static final Pattern MATCH_JAVADOC_NOARG_INLINE_RETURN =
+            CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*\\{?@(return|see)\\s+\\S");


@see tag is also covered by this regex, but the property name and javadoc mention only @return tag. Does it make sense to give the option more generic name (e.g. allowInlineTags), otherwise it is misleading? Or do we want to cover only the inline return tag?

Hey @rdiachenko, thanks for the review. I believe we care about @return tag only. I kept the see in the regex just to be compatible with the MATCH_JAVASOC_NOARG, but I don't believe it's used anywhere. If I am not mistaken the see tag is completely optional and we don't do any checks about it, as there is no need.

rdiachenko

lgtm

romani · 2025-03-29T14:17:28Z

GitHub, generate site

romani

thanks a lot !!!

yes, better to keep it as property to allow users of different jdk to have behavior to match javadoc tool

romani · 2025-03-29T14:26:51Z

@mahfouz72 , FYI.
interesting case on javadoc, different versions of it, and we should comply.
May be we need jdk version to be defined by user to let Checks understand what behavior is expected.

romani · 2025-03-29T14:28:35Z

@kkoutsilis , in future PRs, please try to avoid Javadoc checks that are not based on AST, we plan to do this summer major update, so in ideal scenario we will be able to migrate all Javadoc checks that are regexp based to AST, so it will be a way less problems in support of them.

github-actions · 2025-03-29T16:42:23Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4023370_20250329161936/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/4023370_20250329161936/checks/javadoc/javadocmethod.html#Properties

nrmancuso

Looks good, two minor items:

nrmancuso · 2025-03-31T12:52:49Z

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java

+    /**
+     * Setter to control whether to allow inline return tag.
+     *
+     * @param value a {@code Boolean} value


Suggested change

* @param value a {@code Boolean} value

* @param value a {@code boolean} value

nrmancuso · 2025-03-31T12:55:45Z

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocMethodCheck.xml

@@ -74,6 +74,9 @@
               <description>Specify the access modifiers where Javadoc comments are
 checked.</description>
            </property>
+            <property default-value="false" name="allowInlineReturn" type="boolean">
+               <description>Control whether to allow inline return tag.</description>


Suggested change

<description>Control whether to allow inline return tag.</description>

<description>Control whether to allow inline return tags.</description>

kkoutsilis · 2025-03-31T21:41:54Z

Hey @nrmancuso, thanks for the review. Addressed your comments, feel free to have another look when you get the chance.

nrmancuso

Good stuff! 🎉

JnRouvignac · 2025-04-02T08:36:35Z

Oh! Thank you so much @kkoutsilis!!!!

JnRouvignac · 2025-04-02T08:38:38Z

Too bad it missed the 10.22.0 release by a few days.
Fine, I'll wait 😀

kkoutsilis · 2025-04-02T08:41:41Z

Oh! Thank you so much @kkoutsilis!!!!

Happy to help. Hope this unblocks you 🙏

romani · 2025-04-02T12:47:21Z

@JnRouvignac ,
community not only doing fixed, they also automated release process, so we can release at any time, by any user request.
fix is released https://github.com/checkstyle/checkstyle/releases/tag/checkstyle-10.23.0

romani · 2025-04-02T12:49:14Z

@kkoutsilis , would you like us to recommend on next issue?

kkoutsilis · 2025-04-02T12:54:54Z

@kkoutsilis , would you like us to recommend on next issue?

If you have a priority to any issue I'm happy to have a look as always 🙂

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java

JnRouvignac · 2025-04-09T16:32:47Z

@JnRouvignac , community not only doing fixed, they also automated release process, so we can release at any time, by any user request. fix is released https://github.com/checkstyle/checkstyle/releases/tag/checkstyle-10.23.0

Excellent! Thank you so much for the quick release!
Sorry for the late response, but I wanted to use it in my project before posting feedback here.

I can confirm this works for us, and the feature has benefited us a lot!!

255 files changed, 647 insertions(+), 2742 deletions(-)

I potentially noticed one small thing to improve ({@return} on multiple lines seem to require a final dot?), but I'll test some more and follow-up separately about it.

Again, thank you so much @kkoutsilis!

kkoutsilis · 2025-04-09T18:17:00Z

@kkoutsilis , would you like us to recommend on next issue?

@romani I am looking for the next issue to pick up, any recommendations or preferences??

romani · 2025-04-28T19:56:16Z

@kkoutsilis , please look at discord.

kkoutsilis force-pushed the 9745 branch 2 times, most recently from a295b06 to 0d01a5f Compare March 22, 2025 09:44

kkoutsilis force-pushed the 9745 branch 2 times, most recently from cedb415 to 4023370 Compare March 24, 2025 18:11

romani assigned rdiachenko Mar 25, 2025

rdiachenko reviewed Mar 25, 2025

View reviewed changes

rdiachenko approved these changes Mar 27, 2025

View reviewed changes

rdiachenko assigned romani and unassigned rdiachenko Mar 27, 2025

romani mentioned this pull request Mar 29, 2025

Github generate site fails to generate links with anchors. #14857

Closed

romani approved these changes Mar 29, 2025

View reviewed changes

romani requested a review from nrmancuso March 29, 2025 14:24

romani assigned nrmancuso and unassigned romani Mar 29, 2025

nrmancuso requested changes Mar 31, 2025

View reviewed changes

Issue checkstyle#9745: Added JavadocMethod inline return tag support

a056575

kkoutsilis force-pushed the 9745 branch from 4023370 to a056575 Compare March 31, 2025 21:40

nrmancuso approved these changes Apr 1, 2025

View reviewed changes

nrmancuso merged commit 3f0fec8 into checkstyle:master Apr 1, 2025
114 of 115 checks passed

kkoutsilis deleted the 9745 branch April 1, 2025 13:56

kkoutsilis commented Apr 2, 2025

View reviewed changes

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java Show resolved Hide resolved

kkoutsilis mentioned this pull request Apr 2, 2025

minor: Update JavadocMethodCheck allowInlineReturn release version #16742

Merged

	* @param value a {@code Boolean} value
	* @param value a {@code boolean} value

	<description>Control whether to allow inline return tag.</description>
	<description>Control whether to allow inline return tags.</description>

Uh oh!

Issue #9745: Added JavadocMethod inline return tag support #16605

Issue #9745: Added JavadocMethod inline return tag support #16605

Uh oh!

Conversation

kkoutsilis commented Mar 18, 2025

Uh oh!

romani commented Mar 19, 2025

Uh oh!

kkoutsilis commented Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

romani commented Mar 22, 2025

Uh oh!

kkoutsilis commented Mar 24, 2025

Uh oh!

romani commented Mar 24, 2025

Uh oh!

kkoutsilis commented Mar 24, 2025

Uh oh!

github-actions bot commented Mar 24, 2025

Uh oh!

romani commented Mar 24, 2025

Uh oh!

kkoutsilis commented Mar 24, 2025

Uh oh!

github-actions bot commented Mar 24, 2025

Uh oh!

rdiachenko Mar 25, 2025

Choose a reason for hiding this comment

Uh oh!

kkoutsilis Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rdiachenko left a comment

Choose a reason for hiding this comment

Uh oh!

romani commented Mar 29, 2025

Uh oh!

romani left a comment

Choose a reason for hiding this comment

Uh oh!

romani commented Mar 29, 2025

Uh oh!

romani commented Mar 29, 2025

Uh oh!

github-actions bot commented Mar 29, 2025

Uh oh!

nrmancuso left a comment

Choose a reason for hiding this comment

Uh oh!

nrmancuso Mar 31, 2025

Choose a reason for hiding this comment

Uh oh!

nrmancuso Mar 31, 2025

Choose a reason for hiding this comment

Uh oh!

kkoutsilis commented Mar 31, 2025

Uh oh!

nrmancuso left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JnRouvignac commented Apr 2, 2025

Uh oh!

JnRouvignac commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkoutsilis commented Apr 2, 2025

Uh oh!

romani commented Apr 2, 2025

Uh oh!

romani commented Apr 2, 2025

Uh oh!

kkoutsilis commented Apr 2, 2025

Uh oh!

Uh oh!

JnRouvignac commented Apr 9, 2025

Uh oh!

kkoutsilis commented Mar 19, 2025 •

edited

Loading

kkoutsilis Mar 27, 2025 •

edited

Loading

JnRouvignac commented Apr 2, 2025 •

edited

Loading