Details
-
Enhancement
-
Resolution: Fixed
-
P3
-
21
-
None
-
b23
Description
TagletWriterImpl.linkSeeReferenceOutput has the following signature:
/**
* Worker method to generate a link from the information in different kinds of tags,
* such as {@code {@link ...}} tags, {@code @see ...} tags and the {@code link} markup tag
* in a {@code {@snippet ...}} tag.
*
* @param holder the element that has the documentation comment containing the information
* @param refTree the tree node containing the information, or {@code null} if not available
* @param refSignature the normalized signature of the target of the reference
* @param ref the target of the reference
* @param tagName the name of the tag in the source, to be used in diagnostics
* @param isLinkPlain {@code true} if the link should be presented in "plain" font,
* or {@code false} for "code" font
* @param label the label for the link,
* or an empty item to use a default label derived from the signature
* @param reportWarning a function to report warnings about issues found in the reference
*
* @return the output containing the generated link, or content indicating an error
*/
private Content linkSeeReferenceOutput(Element holder,
DocTree refTree,
String refSignature,
Element ref,
String tagName,
boolean isLinkPlain,
Content label,
BiConsumer<String, Object[]> reportWarning) {
It would be better to make the use of tagName either optional or remove it altogether, and refocus diagnostics on the reference, not so much on the enclosing tag.
/**
* Worker method to generate a link from the information in different kinds of tags,
* such as {@code {@link ...}} tags, {@code @see ...} tags and the {@code link} markup tag
* in a {@code {@snippet ...}} tag.
*
* @param holder the element that has the documentation comment containing the information
* @param refTree the tree node containing the information, or {@code null} if not available
* @param refSignature the normalized signature of the target of the reference
* @param ref the target of the reference
* @param tagName the name of the tag in the source, to be used in diagnostics
* @param isLinkPlain {@code true} if the link should be presented in "plain" font,
* or {@code false} for "code" font
* @param label the label for the link,
* or an empty item to use a default label derived from the signature
* @param reportWarning a function to report warnings about issues found in the reference
*
* @return the output containing the generated link, or content indicating an error
*/
private Content linkSeeReferenceOutput(Element holder,
DocTree refTree,
String refSignature,
Element ref,
String tagName,
boolean isLinkPlain,
Content label,
BiConsumer<String, Object[]> reportWarning) {
It would be better to make the use of tagName either optional or remove it altogether, and refocus diagnostics on the reference, not so much on the enclosing tag.