From d756233828fa8c9f35ca83a29eee4fad8d016349 Mon Sep 17 00:00:00 2001
From: Xavier Shay <xavier@rhnh.net>
Date: Sun, 26 Aug 2012 13:36:23 -0700
Subject: [PATCH] README and wording updates.

---
 README.md              | 60 +++++++++++++++++++++++++++++++++++++-----
 lib/cane/cli/parser.rb | 11 ++++----
 2 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 83ffbbd..b7114ab 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,10 @@ Customize behaviour with a wealth of options:
     > cane --help
     Usage: cane [options]
 
-    You can also put these options in a .cane file.
+    Default options are loaded from a .cane file in the current directory.
+
+        -r, --require FILE               Load a Ruby file containing user-defined checks
+        -c, --check CLASS                Use the given user-defined check
 
             --abc-glob GLOB              Glob to run ABC metrics over (default: {app,lib}/**/*.rb)
             --abc-max VALUE              Ignore methods under this complexity (default: 15)
@@ -54,16 +57,15 @@ Customize behaviour with a wealth of options:
         -v, --version                    Show version
         -h, --help                       Show this message
 
-Set default options into a `.cane` file:
+Set default options using a `.cane` file:
 
     > cat .cane
     --no-doc
     --abc-glob **/*.rb
     > cane
 
-It works just like this:
-
-    > cane --no-doc --abc-glob '**/*.rb'
+It works exactly the same as specifying the options on the command-line.
+Command-line arguments will override arguments specified in the `.cane` file.
 
 ## Integrating with Rake
 
@@ -94,7 +96,9 @@ on to an existing application that may already have many violations. By setting
 the maximum to the current number, no immediate changes will be required to
 your existing code base, but you will be protected from things getting worse.
 
-You can also consider defining exclusions for each violation (see below).
+You may also consider beginning with high thresholds and ratcheting them down
+over time, or defining exclusions for specific troublesome violations (not
+recommended).
 
 ## Integrating with SimpleCov
 
@@ -120,12 +124,54 @@ You can use a `SimpleCov` formatter to create the required file:
 
     SimpleCov.formatter = SimpleCov::Formatter::QualityFormatter
 
+## Implementing your own checks
+
+Checks must implement:
+
+* A class level `options` method that returns a hash of available options. This
+  will be included in help output if the check is added before `--help`. If
+  your check does not require any configuration, return an empty hash.
+* A one argument constructor, into which will be passed the options specified
+  for your check.
+* A `violations` method that returns an array of violations.
+
+See existing checks for guidance. Create your check in a new file:
+
+    # unhappy.rb
+    class UnhappyCheck < Struct.new(:opts)
+      def self.options
+        {
+          unhappy_file: ["File to check", default: [nil]]
+        }
+      end
+
+      def violations
+        [
+          description: "Files are unhappy",
+          file:        opts.fetch(:unhappy_file),
+          label:       ":("
+        ]
+      end
+    end
+
+Include your check either using command-line options:
+
+    cane -r unhappy.rb --check UnhappyCheck --unhappy-file myfile
+
+Or in your rake task:
+
+    require 'unhappy'
+
+    Cane::RakeTask.new(:quality) do |c|
+      c.use UnhappyCheck, unhappy_file: 'myfile'
+    end
+
 ## Compatibility
 
 Requires MRI 1.9, since it depends on the `ripper` library to calculate
 complexity metrics. This only applies to the Ruby used to run Cane, not the
 project it is being run against. In other words, you can run Cane against your
-1.8 project.
+1.8 or JRuby project.
 
 ## Support
 
diff --git a/lib/cane/cli/parser.rb b/lib/cane/cli/parser.rb
index 290a526..2fd1ee1 100644
--- a/lib/cane/cli/parser.rb
+++ b/lib/cane/cli/parser.rb
@@ -23,7 +23,7 @@ def initialize(stdout = $stdout)
         @stdout = stdout
 
         add_banner
-        add_custom_checks
+        add_user_defined_checks
 
         Cane.default_checks.each do |check|
           add_check_options(check)
@@ -59,18 +59,19 @@ def add_banner
         parser.banner = <<-BANNER
 Usage: cane [options]
 
-You can also put these options in a .cane file.
+Default options are loaded from a .cane file in the current directory.
 
 BANNER
       end
 
-      def add_custom_checks
-        description = "Load a Ruby file containing custom checks"
+      def add_user_defined_checks
+        description = "Load a Ruby file containing user-defined checks"
         parser.on("-r", "--require FILE", description) do |f|
           load(f)
         end
 
-        parser.on("-c", "--check CLASS", "Use the given check") do |c|
+        description = "Use the given user-defined check"
+        parser.on("-c", "--check CLASS", description) do |c|
           check = Kernel.const_get(c)
           options[:checks] << check
           add_check_options(check)