JAL-1854 two more rules, readme notes

[jalview.git] / resources / checkstyle / README.txt

diff --git a/resources/checkstyle/README.txt b/resources/checkstyle/README.txt
index 7ad1268..1c2aced 100644 (file)
--- a/resources/checkstyle/README.txt
+++ b/resources/checkstyle/README.txt
@@ -23,7 +23,7 @@ Config
                checkstyle-suppress.xml : rules to exclude certain checks / files
                import-control.xml      : package import rules
        
-       Checkstyle error messages can be customised. I've done this for TypeName as an example.
+       Checkstyle error messages can be customised. See TypeName for an example.
 
 How to use checkstyle
 ---------------------
@@ -33,9 +33,8 @@ How to use checkstyle
                - notice CheckstyleNature gets added to the .project file
                - don't commit this file unless we all agree to!
                - Checkstyle will run as you recompile changed code
-               - checking the whole project can be slow and may hang - not recommended for now
 
-       Option 2: on selected code
+       Option 2: on demand on selected code
                - right-click on a class or package and Checkstyle | Check code with checkstyle
 
 Checkstyle rules
@@ -46,10 +45,23 @@ Checkstyle rules
        - which rules to use
        - what naming and layout standards to apply
        - settings for complexity metrics
-       - whether any rules should report error instead of warning  
+       - whether any rules should report an error instead of a warning  
        
-Gotchas
--------
+Suppressing findings
+--------------------
+       If there are warnings you judge it ok to suppress, your options are
+       (from most global to most local scope):
+       - remove the rule entirely
+       - adjust its properties
+       - add an entry in checkstyle-suppress.xml to skip the file for the rule
+       - add comments around the reported source lines
+               // CHECKSTYLE.OFF: RuleName
+               source code here
+               // CHECKSTYLE.ON: RuleName
+       The suppression should be as localised as possible, to avoid false negatives.
+       
+Tips
+----
        Sometimes checkstyle needs a kick before it will refresh its findings.
        A whitespace edit in checkstyle.xml usually does this. There may be better ways.
        
@@ -62,4 +74,8 @@ Gotchas
        that, carefully check / back out / redo any recent changes to its config.
        
        Putting <!-- XML comments --> inside a checkstyle <module> causes it to be ignored!
-       
\ No newline at end of file
+       
+       If a rule doesn't behave as you expected, read its documentation carefully, including
+       the use and default value of any properties.
+       
+       To highlight a single rule's findings, you could temporarily raise its severity to error.