eclipse-jdt / eclipse-jdt/eclipse.jdt.core

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

Open
#1,583 7 comments 3 reactions 0 assignees View on GitHub
bug help wanted javadoc
Dominant language
Java
Stars
237
Forks
195
Avg merge
1d 10h
Merged PRs (30d)
49

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](https://github.com/eclipse-jdt/eclipse.jdt.core/assets/567706/cd8172f4-da5a-4b33-9cb5-b32ca3ddc1a9)

```
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

Open the contributing guide

Research direction

Start by reproducing the warning with JDT javadoc validation enabled, the shown preferences, and a Javadoc @snippet tag. Trace the missing-tag-description validation for @snippet; done means the valid snippet no longer produces “Description expected after @snippet” while other applicable missing descriptions still do.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
compilers
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.