From 2992f907771afcf98ddf095dcbc3d869dbe8a1a9 Mon Sep 17 00:00:00 2001 From: Rick Giles Date: Tue, 10 Dec 2002 23:55:08 +0000 Subject: [PATCH] more Javadoc --- .../tools/checkstyle/checks/HeaderCheck.java | 33 ++++++++++++++++++- .../checkstyle/checks/IllegalImportCheck.java | 6 +++- .../checkstyle/checks/PackageNameCheck.java | 9 ++++- .../checkstyle/checks/ParenPadCheck.java | 4 +-- .../checks/RedundantImportCheck.java | 12 +++++-- .../checkstyle/checks/RegexpHeaderCheck.java | 31 ++++++++++++++--- 6 files changed, 83 insertions(+), 12 deletions(-) diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/HeaderCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/HeaderCheck.java index 5b606062c..ab9b32e7b 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/HeaderCheck.java +++ b/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; /** + *

* Checks the header of the source against a fixed header file. - * + *

*

* Rationale: In most projects each file must have a fixed header, * since usually the header contains copyright information. *

+ *

The header contents are specified in the file identified by property + * headerFile. + *

+ *

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. + *

* + *

This property is very useful for supporting headers that contain copyright + * dates. For example, consider the following header:

+ * + * 
+ * 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: ///////////////////////////////////////////////////////////////////////
+ *
+ * + *

Since the year information will change over time, you can tell checkstyle + * to ignore line 3 by setting property ignoreLines to 3.

+ *

+ * An example of how to configure the check to use header file + * "java.header" and ignore lines 3 and 5 is: + *

+ * 
+ * <config name="HeaderCheck">
+ *    <property name="headerFile" value="java.header"/>
+ *    <property name="ignoreLines" value="3, 5"/>
+ * </config>
+ *
* @author Lars Kühne */ public class HeaderCheck diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/IllegalImportCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/IllegalImportCheck.java index 8dc2928cc..22f098639 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/IllegalImportCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/IllegalImportCheck.java @@ -26,7 +26,11 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes; /** *

* Checks for imports from a set of illegal packages. - * By default, the check rejects all sun.* packages. + * By default, the check rejects all sun.* packages + * since programs that contain direct calls to the sun.* packages + * are + * not 100% Pure Java. + *

* To reject other packages, set property illegalPkgs to a comma-separated * list of the illegal packages. *

diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/PackageNameCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/PackageNameCheck.java index 75d62ce10..f0deee2b4 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/PackageNameCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/PackageNameCheck.java @@ -29,7 +29,14 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes; * * regular expression * and defaults to - * ^[a-z]+(\\.[a-zA-Z_][a-zA-Z_0-9]*)*$. + * ^[a-z]+(\.[a-zA-Z_][a-zA-Z_0-9]*)*$. + *

+ * The default format has been chosen to match the requirements in the + * + * Java Language specification and the Sun coding conventions. + * However both underscores and uppercase letters are rather uncommon, + * so most projects should probably use + * ^[a-z]+(\.[a-z][a-z0-9]*)*$. *

*

* An example of how to configure the check is: diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/ParenPadCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/ParenPadCheck.java index 0efbbdb78..3032c5141 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/ParenPadCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/ParenPadCheck.java @@ -46,8 +46,8 @@ import com.puppycrawl.tools.checkstyle.api.Utils; * <config name="ParenPadCheck"/> * *

- * 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: *

* 
  * <config name="ParenPadCheck">
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RedundantImportCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RedundantImportCheck.java
index 5a32eb486..bdaef6fd0 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RedundantImportCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RedundantImportCheck.java
@@ -29,10 +29,16 @@ import java.util.HashSet;
 
 /**
  * 

- * Checks for imports that are redundant, where a redundant import is
- * from package java.lang, 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:
  * 

+ *
  * 

  * An example of how to configure the check is:
  * 

diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java
index 40d63f622..dec72c8ff 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java
+++ b/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;
 
 /**
+ * 

  * Checks the header of the source against a header file that contains a
- * regular expression for each line of the source header.
- *
+* 
+ * regular expression
+ * for each line of the source header.
+ * 

  * 

  * 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.
  * 

  *
- * 

- * TODO: RFE 597676
+ * 
For example, consider the following header file:

+ *
+ * 
+ * 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}
+ * 

+ *
+ * 
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.

+ * An example of how to configure the check to use header file
+ * "java.header" and ignore lines 3 and 5 is:
  * 

+ * 
+ * <config name="RegexpHeaderCheck">
+ *    <property name="headerFile" value="java.header"/>
+ *    <property name="ignoreLines" value="3, 5"/>
+ * </config>
+ * 

  *
  * @author Lars Kühne
  */