JavadocLinkWellKnownApi
Since Checkstyle 14.1.0
Description
Checks that Javadoc comments avoid unnecessary
{@link} and {@linkplain} tags for APIs that are considered well-known. Linking well-known APIs can make comments harder to read without adding much value for the reader.
This check reports {@link} references to configured well-known APIs. Two properties are supported: wellKnownQualifiedPackages and wellKnownSimpleNames.
Both properties are needed because Checkstyle does not resolve Javadoc link targets. For example, java.lang.String contains the package name, so it can be matched through wellKnownQualifiedPackages. However, String only contains the simple name String, so it needs to be matched through wellKnownSimpleNames. Resolution of imports is not a solution since java.lang is implicitly imported.
For wellKnownQualifiedPackages, only references to classes that are direct members of a well-known package are reported. References to a member (for example, String#length()), a nested class (for example, System.Logger), a subpackage (for example, java.lang.ref.WeakReference), and a package itself (for example, java.lang.ref) are not reported.
Properties
| name | description | type | default value | since |
|---|---|---|---|---|
| violateExecutionOnNonTightHtml | Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. | boolean | false |
14.1.0 |
| wellKnownQualifiedPackages | Specify package names whose fully qualified API references should not be linked. | String[] | java.lang |
14.1.0 |
| wellKnownSimpleNames | Specify simple API names that should not be linked. | String[] | String |
14.1.0 |
Examples
To configure the check:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocLinkWellKnownApi"/>
</module>
</module>
Example:
class Example1 {
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@link String}.
*/
public String valid() { return ""; }
// ok, Integer is not in the default wellKnownSimpleNames
/**
* Uses a {@link Integer}.
*/
public Integer validInteger() { return 0; }
// ok, java.util is not in the default wellKnownQualifiedPackages
/**
* Uses a {@link java.util.List}.
*/
public java.util.List validList() { return null; }
// violation 3 lines below """'java.lang.String' should not be linked because
// it belongs to a well-known package."""
/**
* Uses a {@link java.lang.String}.
*/
public String validLangString() { return ""; }
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@linkplain String}.
*/
public String validLinkplain() { return ""; }
// ok, Object is not in the default wellKnownSimpleNames
/**
* Uses a {@linkplain Object}.
*/
public Object validLinkplainObject() { return null; }
// ok, member references are not checked
/**
* Uses a {@link String#length()}.
*/
public int validMember() { return 0; }
// ok, member references are not checked
/**
* Uses a {@link java.lang.Class<String>#getName()}.
*/
public String validMemberQualified() { return ""; }
// ok, subpackage references are not checked
/**
* Uses a {@link java.lang.ref.WeakReference}.
*/
public java.lang.ref.WeakReference validSubpackage() { return null; }
// ok, nested class references are not checked
/**
* Uses a {@link java.lang.System.Logger}.
*/
public java.lang.System.Logger validNestedClass() { return null; }
// ok, package references are not checked
/**
* Uses a {@link java.lang.ref}.
*/
public Class<?> validPackageReference() { return null; }
}
To configure the check with custom well-known APIs:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocLinkWellKnownApi">
<property name="wellKnownQualifiedPackages" value="java.lang, java.util"/>
</module>
</module>
</module>
Example:
class Example2 {
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@link String}.
*/
public String valid() { return ""; }
// ok, Integer is not in the default wellKnownSimpleNames
/**
* Uses a {@link Integer}.
*/
public Integer validInteger() { return 0; }
// violation 3 lines below """'java.util.List' should not be linked because
// it belongs to a well-known package."""
/**
* Uses a {@link java.util.List}.
*/
public java.util.List validList() { return null; }
// violation 3 lines below """'java.lang.String' should not be linked because
// it belongs to a well-known package."""
/**
* Uses a {@link java.lang.String}.
*/
public String validLangString() { return ""; }
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@linkplain String}.
*/
public String validLinkplain() { return ""; }
// ok, Object is not in the default wellKnownSimpleNames
/**
* Uses a {@linkplain Object}.
*/
public Object validLinkplainObject() { return null; }
// ok, member references are not checked
/**
* Uses a {@link String#length()}.
*/
public int validMember() { return 0; }
// ok, member references are not checked
/**
* Uses a {@link java.lang.Class<String>#getName()}.
*/
public String validMemberQualified() { return ""; }
// ok, subpackage references are not checked
/**
* Uses a {@link java.lang.ref.WeakReference}.
*/
public java.lang.ref.WeakReference validSubpackage() { return null; }
// ok, nested class references are not checked
/**
* Uses a {@link java.lang.System.Logger}.
*/
public java.lang.System.Logger validNestedClass() { return null; }
// ok, package references are not checked
/**
* Uses a {@link java.lang.ref}.
*/
public Class<?> validPackageReference() { return null; }
}
To configure the check with a different set of well-known APIs:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocLinkWellKnownApi">
<property name="wellKnownQualifiedPackages" value="java.lang"/>
<property name="wellKnownSimpleNames" value="String, Integer"/>
</module>
</module>
</module>
Example:
class Example3 {
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@link String}.
*/
public String valid() { return ""; }
// violation 3 lines below """'Integer' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@link Integer}.
*/
public Integer validInteger() { return 0; }
// ok, java.util is not configured
/**
* Uses a {@link java.util.List}.
*/
public java.util.List validList() { return null; }
// violation 3 lines below """'java.lang.String' should not be linked because
// it belongs to a well-known package."""
/**
* Uses a {@link java.lang.String}.
*/
public String validLangString() { return ""; }
// violation 3 lines below """'String' should not be linked because it is
// configured as a well-known API."""
/**
* Uses a {@linkplain String}.
*/
public String validLinkplain() { return ""; }
// ok, Object is not configured
/**
* Uses a {@linkplain Object}.
*/
public Object validLinkplainObject() { return null; }
// ok, member references are not checked
/**
* Uses a {@link String#length()}.
*/
public int validMember() { return 0; }
// ok, member references are not checked
/**
* Uses a {@link java.lang.Class<String>#getName()}.
*/
public String validMemberQualified() { return ""; }
// ok, subpackage references are not checked
/**
* Uses a {@link java.lang.ref.WeakReference}.
*/
public java.lang.ref.WeakReference validSubpackage() { return null; }
// ok, nested class references are not checked
/**
* Uses a {@link java.lang.System.Logger}.
*/
public java.lang.System.Logger validNestedClass() { return null; }
// ok, package references are not checked
/**
* Uses a {@link java.lang.ref}.
*/
public Class<?> validPackageReference() { return null; }
}
Example of Usage
Violation Messages
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
Fully Qualified Name
com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocLinkWellKnownApiCheck
Use this fully qualified class name in configuration when an exact class reference is required.