Merge 91abad1 into 61aa58c

src/main/java/com/puppycrawl/tools/checkstyle/checks/naming/MethodNameCheck.java

@@ -26,18 +26,50 @@
 /**
  * <p>
  * Checks that method names conform to a format specified
- * by the format property. The format is a
- * {@link java.util.regex.Pattern regular expression}
- * and defaults to
- * <strong>^[a-z][a-zA-Z0-9]*$</strong>.
+ * by the format property.
  * </p>
  *
  * <p>Also, checks if a method name has the same name as the residing class.
- * The default is false (it is not allowed).  It is legal in Java to have
- * method with the same name as a class.  As long as a return type is specified
+ * The default is false (it is not allowed). It is legal in Java to have
+ * method with the same name as a class. As long as a return type is specified
  * it is a method and not a constructor which it could be easily confused as.
- * <h3>Does not check-style the name of an overridden methods</h3> because the developer does not
+ * Does not check-style the name of an overridden methods because the developer does not
  * have a choice in renaming such methods.
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * Property {@code format} - Specifies valid identifiers.
+ * Default value is {@code "^[a-z][a-zA-Z0-9]*$"}.
+ * </li>
+ * <li>
+ * Property {@code allowClassName} - Controls whether to allow a method name to have the same name
+ * as the residing class name. This is not to be confused with a constructor. An easy mistake is
+ * to place a return type on a constructor declaration which turns it into a method. For example:
+ * <pre>
+ * class MyClass {
+ *     public void MyClass() {} //this is a method
+ *     public MyClass() {} //this is a constructor
+ * }
+ * </pre> Default value is {@code false}.
+ * </li>
+ * <li>
+ * Property {@code applyToPublic} - Controls whether to apply the check to public member.
+ * Default value is {@code true}.
+ * </li>
+ * <li>
+ * Property {@code applyToProtected} - Controls whether to apply the check to protected member.
+ * Default value is {@code true}.
+ * </li>
+ * <li>
+ * Property {@code applyToPackage} - Controls whether to apply the check to package-private member.
+ * Default value is {@code true}.
+ * </li>
+ * <li>
+ * Property {@code applyToPrivate} - Controls whether to apply the check to private member.
+ * Default value is {@code true}.
+ * </li>
+ * </ul>
  *
  * <p>
  * An example of how to configure the check is:
@@ -64,6 +96,8 @@
  *    &lt;property name="allowClassName" value="true"/&gt;
  * &lt;/module&gt;
  * </pre>
+ *
+ * @since 3.0
  */
 public class MethodNameCheck
     extends AbstractAccessControlNameCheck {
@@ -85,7 +119,15 @@ public class MethodNameCheck
     private static final String CANONICAL_OVERRIDE = "java.lang." + OVERRIDE;
 
     /**
-     * For allowing method name to be the same as the class name.
+     * Controls whether to allow a method name to have the same name as the residing class name.
+     * This is not to be confused with a constructor. An easy mistake is to place a return type on
+     * a constructor declaration which turns it into a method. For example:
+     * <pre>
+     * class MyClass {
+     *     public void MyClass() {} //this is a method
+     *     public MyClass() {} //this is a constructor
+     * }
+     * </pre>
      */
     private boolean allowClassName;
 
@@ -139,7 +181,16 @@ public void visitToken(DetailAST ast) {
     }
 
     /**
-     * Sets the property for allowing a method to be the same name as a class.
+     * Setter to controls whether to allow a method name to have the same name as the residing
+     * class name. This is not to be confused with a constructor. An easy mistake is to place
+     * a return type on a constructor declaration which turns it into a method. For example:
+     * <pre>
+     * class MyClass {
+     *     public void MyClass() {} //this is a method
+     *     public MyClass() {} //this is a constructor
+     * }
+     * </pre>
+     *
      * @param allowClassName true to allow false to disallow
      */
     public void setAllowClassName(boolean allowClassName) {

src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java

@@ -114,6 +114,7 @@ public void testAllCheckSectionJavaDocs() throws Exception {
                                 && !"LocalFinalVariableName".equals(sectionName)
                                 && !"LocalVariableName".equals(sectionName)
                                 && !"MemberName".equals(sectionName)
+                                && !"MethodName".equals(sectionName)
                 ) {
                     continue;
                 }

src/xdocs/config_naming.xml

@@ -1030,10 +1030,18 @@ for (int i = 1; i < 10; i++) {}
     </section>
 
     <section name="MethodName">
+      <p>Since Checkstyle 3.0</p>
       <subsection name="Description">
-        <p>Since Checkstyle 3.0</p>
         <p>
-          Validates identifiers for methods.
+          Checks that method names conform to a format specified by the format property.
+        </p>
+        <p>
+          Also, checks if a method name has the same name as the residing class.
+          The default is false (it is not allowed). It is legal in Java to have
+          method with the same name as a class. As long as a return type is specified
+          it is a method and not a constructor which it could be easily confused as.
+          Does not check-style the name of an overridden methods because the developer
+          does not have a choice in renaming such methods.
         </p>
       </subsection>
 
@@ -1057,8 +1065,8 @@ for (int i = 1; i &lt; 10; i++) {}
             <td>allowClassName</td>
             <td>
               Controls whether to allow a method name to have the same
-              name as the residing class name.  This is not to be confused
-              with a constructor.  An easy mistake is to place a return
+              name as the residing class name. This is not to be confused
+              with a constructor. An easy mistake is to place a return
               type on a constructor declaration which turns it into a
               method. For example:
               <pre>
@@ -1107,11 +1115,29 @@ class MyClass {
 
       <subsection name="Examples">
         <p>
-          To configure the check:
+          An example of how to configure the check is:
         </p>
         <source>
 &lt;module name=&quot;MethodName&quot;/&gt;
         </source>
+        <p>
+          An example of how to configure the check for names that begin with a lower case letter,
+          followed by letters, digits, and underscores is:
+        </p>
+        <source>
+&lt;module name="MethodName"&gt;
+   &lt;property name="format" value="^[a-z](_?[a-zA-Z0-9]+)*$"/&gt;
+&lt;/module&gt;
+        </source>
+        <p>
+          An example of how to configure the check to allow method names to be equal to the
+          residing class name is:
+        </p>
+        <source>
+&lt;module name="MethodName"&gt;
+   &lt;property name="allowClassName" value="true"/&gt;
+&lt;/module&gt;
+        </source>
       </subsection>
 
       <subsection name="Example of Usage">