1 /*
2 com.puppycrawl.tools.checkstyle.meta.JavadocMetadataScraper
3 writeXmlOutput = false
4
5
6 */
7
8 package com.puppycrawl.tools.checkstyle.meta.javadocmetadatascraper;
9
10 import java.util.Locale;
11
12 import com.puppycrawl.tools.checkstyle.StatelessCheck;
13 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
14
15
16
17 /**
18 * <p>
19 * Checks the style of elements in annotations.
20 * </p>
21 * <p>
22 * Annotations have three element styles starting with the least verbose.
23 * </p>
24 * <ul>
25 * <li>
26 * {@code ElementStyleOption.COMPACT_NO_ARRAY}
27 * </li>
28 * <li>
29 * {@code ElementStyleOption.COMPACT}
30 * </li>
31 * <li>
32 * {@code ElementStyleOption.EXPANDED}
33 * </li>
34 * </ul>
35 * <p>
36 * To not enforce an element style a {@code ElementStyleOption.IGNORE} type is provided.
37 * The desired style can be set through the {@code elementStyle} property.
38 * </p>
39 * <p>
40 * Using the {@code ElementStyleOption.EXPANDED} style is more verbose.
41 * The expanded version is sometimes referred to as "named parameters" in other languages.
42 * </p>
43 * <p>
44 * Using the {@code ElementStyleOption.COMPACT} style is less verbose.
45 * This style can only be used when there is an element called 'value' which is either
46 * the sole element or all other elements have default values.
47 * </p>
48 * <p>
49 * Using the {@code ElementStyleOption.COMPACT_NO_ARRAY} style is less verbose.
50 * It is similar to the {@code ElementStyleOption.COMPACT} style but single value arrays are
51 * flagged.
52 * With annotations a single value array does not need to be placed in an array initializer.
53 * </p>
54 * <p>
55 * The ending parenthesis are optional when using annotations with no elements.
56 * To always require ending parenthesis use the {@code ClosingParensOption.ALWAYS} type.
57 * To never have ending parenthesis use the {@code ClosingParensOption.NEVER} type.
58 * To not enforce a closing parenthesis preference a {@code ClosingParensOption.IGNORE} type is
59 * provided.
60 * Set this through the {@code closingParens} property.
61 * </p>
62 * <p>
63 * Annotations also allow you to specify arrays of elements in a standard format.
64 * As with normal arrays, a trailing comma is optional.
65 * To always require a trailing comma use the {@code TrailingArrayCommaOption.ALWAYS} type.
66 * To never have a trailing comma use the {@code TrailingArrayCommaOption.NEVER} type.
67 * To not enforce a trailing array comma preference a {@code TrailingArrayCommaOption.IGNORE} type
68 * is provided. Set this through the {@code trailingArrayComma} property.
69 * </p>
70 * <p>
71 * By default, the {@code ElementStyleOption} is set to {@code COMPACT_NO_ARRAY},
72 * the {@code TrailingArrayCommaOption} is set to {@code NEVER},
73 * and the {@code ClosingParensOption} is set to {@code NEVER}.
74 * </p>
75 * <p>
76 * According to the JLS, it is legal to include a trailing comma
77 * in arrays used in annotations but Sun's Java 5 & 6 compilers will not
78 * compile with this syntax. This may in be a bug in Sun's compilers
79 * since eclipse 3.4's built-in compiler does allow this syntax as
80 * defined in the JLS. Note: this was tested with compilers included with
81 * JDK versions 1.5.0.17 and 1.6.0.11 and the compiler included with eclipse 3.4.1.
82 * </p>
83 * <p>
84 * See <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-9.html#jls-9.7">
85 * Java Language specification, §9.7</a>.
86 * </p>
87 * <ul>
88 * <li>
89 * Property {@code elementStyle} - Define the annotation element styles.
90 * Type is {@code
91 * com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$ElementStyleOption}.
92 * Default value is {@code compact_no_array}.
93 * </li>
94 * <li>
95 * Property {@code closingParens} - Define the policy for ending parenthesis.
96 * Type is {@code
97 * com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$ClosingParensOption}.
98 * Default value is {@code never}.
99 * </li>
100 * <li>
101 * Property {@code trailingArrayComma} - Define the policy for trailing comma in arrays.
102 * Type is {@code
103 * com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck$TrailingArrayCommaOption}.
104 * Default value is {@code never}.
105 * </li>
106 * </ul>
107 * <p>
108 * To configure the check:
109 * </p>
110 * <pre>
111 * skipped as not relevant for UTs
112 * </pre>
113 * <p>
114 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
115 * </p>
116 * <p>
117 * Violation Message Keys:
118 * </p>
119 * <ul>
120 * <li>
121 * {@code annotation.incorrect.style}
122 * </li>
123 * <li>
124 * {@code annotation.parens.missing}
125 * </li>
126 * <li>
127 * {@code annotation.parens.present}
128 * </li>
129 * <li>
130 * {@code annotation.trailing.comma.missing}
131 * </li>
132 * <li>
133 * {@code annotation.trailing.comma.present}
134 * </li>
135 * </ul>
136 *
137 * @since 5.0
138 *
139 */
140 @StatelessCheck
141 public abstract class InputJavadocMetadataScraperAnnotationUseStyleCheck extends AbstractCheck {
142 }