Currently, we have to manually insert modules' descriptions in the xdoc files which is very inconvenient as we have to do so every time it changes.
Examples:
description is plainly placed in the template file as text -
|
<subsection name="Description" id="Description"> |
|
<div> |
|
Checks location of annotation on language elements. |
|
By default, Check enforce to locate annotations immediately after documentation block |
|
and before target element, annotation should be located on separate line from target |
|
element. This check also verifies that the annotations are on the same indenting level as |
|
the annotated element if they are not on the same line. |
|
</div> |
|
|
|
<p> |
|
Attention: Elements that cannot have JavaDoc comments like local variables are not in the |
|
scope of this check even though a token type like <code>VARIABLE_DEF</code> would match |
|
them. |
|
</p> |
|
|
|
<p> |
|
Attention: Annotations among modifiers are ignored (looks like false-negative) |
|
as there might be a problem with annotations for return types: |
|
</p> |
|
<source>public @Nullable Long getStartTimeOrNull() { ... }</source> |
|
|
|
<p> |
|
Such annotations are better to keep close to type. |
|
Due to limitations, Checkstyle can not examine the target of an annotation. |
|
</p> |
|
|
|
<p> |
|
Example: |
|
</p> |
|
<source> |
|
@Override |
|
@Nullable |
|
public String getNameIfPresent() { ... } |
|
</source> |
|
</subsection> |
We can create the description macro that would just require us to paste once in template file:
<macro name="description">
<param name="modulePath"
value="src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/AnnotationLocationCheck.java"/>
</macro>
for it to automatically extract current description from the javadoc of module.
Current progress of implementing Description Macro to the check templates:
Currently, we have to manually insert modules' descriptions in the xdoc files which is very inconvenient as we have to do so every time it changes.
Examples:
description is plainly placed in the template file as text -
checkstyle/src/site/xdoc/checks/annotation/annotationlocation.xml.template
Lines 12 to 46 in c88d05a
We can create the description macro that would just require us to paste once in template file:
for it to automatically extract current description from the javadoc of module.
Current progress of implementing Description Macro to the check templates:
checks/annotation
checks/blocks
checks/coding
checks/design
checks/header
checks/imports
checks/javadoc
checks/metrics
checks/misc
checks/modifier
checks/naming
checks/regexp
checks/sizes
checks/whitespace
checks templates with Notes subsection
firefilters
filters