more Javadoc

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/HeaderCheck.java

@@ -29,13 +29,44 @@ import com.puppycrawl.tools.checkstyle.api.Check;
 import org.apache.commons.beanutils.ConversionException;
 
 /**
+ * <p>
  * Checks the header of the source against a fixed header file.
- *
+ * </p>
  * <p>
  * Rationale: In most projects each file must have a fixed header,
  * since usually the header contains copyright information.
  * </p>
+ * <p> The header contents are specified in the file identified by property
+ * headerFile. 
+ * </p>
+ * <p>Property ignoreLines specifies the line numbers to ignore when
+ * matching lines in a header file.
+ * The property type is a comma-separated list of integers and defaults to an
+ * empty list.
+ * </p>
  *
+ * <p>This property is very useful for supporting headers that contain copyright
+ * dates. For example, consider the following header:</p>
+ *
+ * <pre>
+ * line 1: ///////////////////////////////////////////////////////////////////////
+ * line 2: // checkstyle: Checks Java source code for adherence to a set of rules.
+ * line 3: // Copyright (C) 2001  Oliver Burn
+ * line 4: ///////////////////////////////////////////////////////////////////////
+ * </pre>
+ *
+ * <p>Since the year information will change over time, you can tell checkstyle
+ * to ignore line 3 by setting property ignoreLines to <strong>3</strong>.</p>
+ * <p>
+ * An example of how to configure the check to use header file
+ * &quot;java.header&quot; and ignore lines 3 and 5 is:
+ * </p>
+ * <pre>
+ * &lt;config name="HeaderCheck"&gt;
+ *    &lt;property name="headerFile" value="java.header"/&gt;
+ *    &lt;property name="ignoreLines" value="3, 5"/&gt;
+ * &lt;/config&gt;
+ * </pre>
  * @author Lars Kühne
  */
 public class HeaderCheck

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/IllegalImportCheck.java

@@ -26,7 +26,11 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 /**
  * <p>
  * Checks for imports from a set of illegal packages.
- * By default, the check rejects all <code>sun.*</code> packages. 
+ * By default, the check rejects all <code>sun.*</code> packages
+ * since programs that contain direct calls to the <code>sun.*</code> packages
+ * are <a href="http://java.sun.com/products/jdk/faq/faq-sun-packages.html">
+ * not 100% Pure Java</a>.
+ * </p>
  * To reject other packages, set property illegalPkgs to a comma-separated
  * list of the illegal packages.  
  * </p>

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/PackageNameCheck.java

@@ -29,7 +29,14 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes;
  * <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">
  * regular expression</a>
  * and defaults to
- * <strong>^[a-z]+(\\.[a-zA-Z_][a-zA-Z_0-9]*)*$</strong>.
+ * <strong>^[a-z]+(\.[a-zA-Z_][a-zA-Z_0-9]*)*$</strong>.
+ * </p>
+ * The default format has been chosen to match the requirements in the
+ * <a href="http://java.sun.com/docs/books/jls/second_edition/html/packages.doc.html#40169">
+ * Java Language specification</a> and the Sun coding conventions.
+ * However both underscores and uppercase letters are rather uncommon,
+ * so most projects should probably use
+ * <strong>^[a-z]+(\.[a-z][a-z0-9]*)*$</strong>.
  * </p>
  * <p>
  * An example of how to configure the check is:

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/ParenPadCheck.java

@@ -46,8 +46,8 @@ import com.puppycrawl.tools.checkstyle.api.Utils;
  * <config name="ParenPadCheck"/>
  * </pre> 
  * <p>
- * An example of how to configure the check to require spaces for the parentheses of
- * constructor, method, and super constructor invocations is:
+ * An example of how to configure the check to require spaces for the
+ * parentheses of constructor, method, and super constructor invocations is:
  * </p>
  * <pre>
  * &lt;config name="ParenPadCheck"&gt;

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RedundantImportCheck.java

@@ -29,10 +29,16 @@ import java.util.HashSet;
 
 /**
  * <p>
- * Checks for imports that are redundant, where a redundant import is
- * from package <code>java.lang</code>, is from the same package as the class,
- * or is a duplicate import.
+ * Checks for imports that are redundant. An import statement is
+ * considered redundant if:
  * </p>
+ *<ul>
+ *  <li>It is a duplicate of another import. This is, when a class is imported
+ *  more than once.</li>
+ *  <li>The class imported is from the <code>java.lang</code> package.
+ *  For example importing <code>java.lang.String</code>.</li>
+ *  <li>The class imported is from the same package.</li>
+ *</ul>
  * <p>
  * An example of how to configure the check is:
  * </p>

src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java

@@ -24,9 +24,12 @@ import org.apache.commons.beanutils.ConversionException;
 import com.puppycrawl.tools.checkstyle.api.Utils;
 
 /**
+ * <p>
  * Checks the header of the source against a header file that contains a
- * regular expression for each line of the source header.
- *
+* <a href="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">
+ * regular expression</a>
+ * for each line of the source header.
+ * </p>
  * <p>
  * Rationale: In some projects checking against a fixed header
  * is not sufficient (see {@link HeaderCheck}), e.g.
@@ -34,9 +37,29 @@ import com.puppycrawl.tools.checkstyle.api.Utils;
  * is not static.
  * </p>
  *
- * <p>
- * TODO: RFE 597676
+ * <p>For example, consider the following header file:</p>
+ *
+ * <pre>
+ * line 1: /{71}
+ * line 2: // checkstyle: Checks Java source code for adherence to a set of rules\.
+ * line 3: // Copyright \(C\) \d\d\d\d  Oliver Burn
+ * line 4: // Last modification by \$Author.*\$
+ * line 5: /{71}
+ * </pre>
+ *
+ * <p>Lines 1 and 5 demonstrate a more compact notation for 71 '/'
+ * characters. Line 3 enforces that the copyright notice includes a four digit
+ * year. Line 4 is an example how to enforce revision control keywords in a file
+ * header.</p>
+ * An example of how to configure the check to use header file
+ * &quot;java.header&quot; and ignore lines 3 and 5 is:
  * </p>
+ * <pre>
+ * &lt;config name="RegexpHeaderCheck"&gt;
+ *    &lt;property name="headerFile" value="java.header"/&gt;
+ *    &lt;property name="ignoreLines" value="3, 5"/&gt;
+ * &lt;/config&gt;
+ * </pre>
  *
  * @author Lars Kühne
  */