Details
-
Type:
Bug
-
Status: New
-
Priority:
P4
-
Resolution: Unresolved
-
Affects Version/s: 15
-
Fix Version/s: None
-
Component/s: specification
-
CPU:generic
-
OS:generic
Description
A DESCRIPTION OF THE PROBLEM :
It appears the Standard Doclet supports using the {@summary} javadoc tag within the @deprecated block tag to include more than the first sentence in the summary.
However, the [Documentation Comment Specification for the Standard Doclet|https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html] does not mention this.
It should therefore by adjusted by:
- Mentioning {@summary} usage in the section about @deprecated
- Changing the {@summary} section to mention that it is allowed for the @deprecated block tag as well
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Create javadoc for the class provided below and compare what is included the summary about deprecation.
---------- BEGIN SOURCE ----------
public class Test {
/**
* @deprecated First sentence. Second one.
*/
@Deprecated
public void test1() {
}
/**
* @deprecated {@summary First sentence. Second one.}
*/
@Deprecated
public void test2() {
}
}
---------- END SOURCE ----------
It appears the Standard Doclet supports using the {@summary} javadoc tag within the @deprecated block tag to include more than the first sentence in the summary.
However, the [Documentation Comment Specification for the Standard Doclet|https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html] does not mention this.
It should therefore by adjusted by:
- Mentioning {@summary} usage in the section about @deprecated
- Changing the {@summary} section to mention that it is allowed for the @deprecated block tag as well
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Create javadoc for the class provided below and compare what is included the summary about deprecation.
---------- BEGIN SOURCE ----------
public class Test {
/**
* @deprecated First sentence. Second one.
*/
@Deprecated
public void test1() {
}
/**
* @deprecated {@summary First sentence. Second one.}
*/
@Deprecated
public void test2() {
}
}
---------- END SOURCE ----------