forked from checkstyle/checkstyle
-
Notifications
You must be signed in to change notification settings - Fork 2
/
JavadocStyleCheck.xml
94 lines (94 loc) · 4.36 KB
/
JavadocStyleCheck.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle-metadata>
<module>
<check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck"
name="JavadocStyle"
parent="com.puppycrawl.tools.checkstyle.TreeWalker">
<description><p>
Validates Javadoc comments to help ensure they are well formed.
</p>
<p>
The following checks are performed:
</p>
<ul>
<li>
Ensures the first sentence ends with proper punctuation
(That is a period, question mark, or exclamation mark, by default).
Javadoc automatically places the first sentence in the method summary
table and index. Without proper punctuation the Javadoc may be malformed.
All items eligible for the {@code {@inheritDoc}} tag are exempt from this
requirement.
</li>
<li>
Check text for Javadoc statements that do not have any description.
This includes both completely empty Javadoc, and Javadoc with only tags
such as {@code @param} and {@code @return}.
</li>
<li>
Check text for incomplete HTML tags. Verifies that HTML tags have
corresponding end tags and issues an "Unclosed HTML tag found:" error if not.
An "Extra HTML tag found:" error is issued if an end tag is found without
a previous open tag.
</li>
<li>
Check that a package Javadoc comment is well-formed (as described above).
</li>
<li>
Check for allowed HTML tags. The list of allowed HTML tags is
"a", "abbr", "acronym", "address", "area", "b", "bdo", "big", "blockquote",
"br", "caption", "cite", "code", "colgroup", "dd", "del", "dfn", "div", "dl",
"dt", "em", "fieldset", "font", "h1", "h2", "h3", "h4", "h5", "h6", "hr",
"i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", "samp", "small",
"span", "strong", "sub", "sup", "table", "tbody", "td", "tfoot", "th",
"thead", "tr", "tt", "u", "ul", "var".
</li>
</ul>
<p>
These checks were patterned after the checks made by the
<a href="https://maven-doccheck.sourceforge.net">DocCheck</a> doclet
available from Sun. Note: Original Sun's DocCheck tool does not exist anymore.
</p></description>
<properties>
<property default-value="private"
name="scope"
type="com.puppycrawl.tools.checkstyle.api.Scope">
<description>Specify the visibility scope where Javadoc comments are checked.</description>
</property>
<property name="excludeScope" type="com.puppycrawl.tools.checkstyle.api.Scope">
<description>Specify the visibility scope where
Javadoc comments are not checked.</description>
</property>
<property default-value="true" name="checkFirstSentence" type="boolean">
<description>Control whether to check the first
sentence for proper end of sentence.</description>
</property>
<property default-value="([.?!][ \t\n\r\f&lt;])|([.?!]$)"
name="endOfSentenceFormat"
type="java.util.regex.Pattern">
<description>Specify the format for matching
the end of a sentence.</description>
</property>
<property default-value="false" name="checkEmptyJavadoc" type="boolean">
<description>Control whether to check if the Javadoc
is missing a describing text.</description>
</property>
<property default-value="true" name="checkHtml" type="boolean">
<description>Control whether to check for incomplete HTML tags.</description>
</property>
<property default-value="ANNOTATION_DEF,ANNOTATION_FIELD_DEF,CLASS_DEF,CTOR_DEF,ENUM_CONSTANT_DEF,ENUM_DEF,INTERFACE_DEF,METHOD_DEF,PACKAGE_DEF,VARIABLE_DEF,RECORD_DEF,COMPACT_CTOR_DEF"
name="tokens"
type="java.lang.String[]"
validation-type="tokenSet">
<description>tokens to check</description>
</property>
</properties>
<message-keys>
<message-key key="javadoc.empty"/>
<message-key key="javadoc.extraHtml"/>
<message-key key="javadoc.incompleteTag"/>
<message-key key="javadoc.noPeriod"/>
<message-key key="javadoc.unclosedHtml"/>
</message-keys>
</check>
</module>
</checkstyle-metadata>