eclipse-jdt/eclipse.jdt.core

[18] False javadoc warning when using snippets and validate Missing Tag: "Description expected after @snippet"

Open

#1,583 opened on Nov 10, 2023

View on GitHub
 (7 comments) (3 reactions) (0 assignees)Java (183 forks)auto 404
bughelp wantedjavadoc

Repository metrics

Stars
 (233 stars)
PR merge metrics
 (PR metrics pending)

Description

If javadoc validation is turned on and a @snippet tag is used with the below setting JDT will give a warning.

Screen Shot 2023-11-10 at 9 00 28 AM

Description expected after @snippet

Here are the javadoc prefs:

org.eclipse.jdt.core.compiler.problem.invalidJavadoc=warning
org.eclipse.jdt.core.compiler.problem.invalidJavadocTags=enabled
org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsDeprecatedRef=disabled
org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsNotVisibleRef=enabled
org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsVisibility=public
org.eclipse.jdt.core.compiler.problem.missingJavadocComments=warning
org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=public
org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_tags
org.eclipse.jdt.core.compiler.problem.missingJavadocTags=warning
org.eclipse.jdt.core.compiler.problem.missingJavadocTagsMethodTypeParameters=enabled
org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=public

The below is the problematic setting.

org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_tags

Contributor guide

Research direction
Investigate the Javadoc validation code for the @snippet tag to understand why the 'Missing Tag: Description expected after @snippet' warning is triggered incorrectly when 'missingJavadocTagDescription=all standard tags' is set.
Tech stack
java
Domain
tooling
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Git
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60