cane 2.2.2 → 2.2.3

data/HISTORY.md

@@ -1,5 +1,11 @@
 # Cane History
 
+## 2.2.3 - 3 September 2012 (e4fe90ee)
+
+* Bugfix: Allow multiple spaces before class name. (#34)
+* Bugfix: Remove wacky broken conditional in AbcCheck. (#33)
+* Doc: Better guidance on class level comments. (#35)
+
 ## 2.2.2 - 29 August 2012 (3a9be454)
 
 * Bugfix: Stricter magic comment regex to avoid false positives (#31)

data/README.md

@@ -24,7 +24,7 @@ a non-zero exit code if any quality checks fail. Also, a report:
       lib/cane.rb:20   Line length >80
       lib/cane.rb:42   Trailing whitespace
 
-    Classes are not documented (1):
+    Class definitions require explanatory comments on preceeding line (1):
       lib/cane:3  SomeClass
 
 Customize behaviour with a wealth of options:
@@ -167,6 +167,31 @@ Or in your rake task:
       c.use UnhappyCheck, unhappy_file: 'myfile'
     end
 
+## Protips
+
+### Writing class level documentation
+
+Classes are commonly the first entry point into a code base, often for an
+oncall engineer responding to an exception, so provide enough information to
+orient first-time readers.
+
+A good class level comment should answer the following:
+
+* Why does this class exist?
+* How does it fit in to the larger system?
+* Explanation of any domain-specific terms.
+
+If you have specific documentation elsewhere (say, in the README or a wiki), a
+link to that suffices.
+
+If the class is a known entry point, such as a regular background job that can
+potentially fail, then also provide enough context that it can be efficently
+dealt with. In the background job case:
+
+* Should it be retried?
+* What if it failed 5 days ago and we're only looking at it now?
+* Who cares that this job failed?
+
 ## Compatibility
 
 Requires MRI 1.9, since it depends on the `ripper` library to calculate
@@ -176,9 +201,7 @@ project it is being run against. In other words, you can run Cane against your
 
 ## Support
 
-[Ask questions on Stack
-Overflow](http://stackoverflow.com/questions/ask?tags=ruby+cane). We keep an
-eye on new cane questions.
+Make a [new github issue](https://github.com/square/cane/issues/new).
 
 ## Contributing
 

data/lib/cane/abc_check.rb

@@ -33,7 +33,7 @@ module Cane
     end
 
     def violations
-      return [] if opts[:no_abc] == false
+      return [] if opts[:no_abc]
 
       order worker.map(file_names) {|file_name|
         find_violations(file_name)

data/lib/cane/doc_check.rb

@@ -6,6 +6,9 @@ module Cane
   # comment immediately preceeding.
   class DocCheck < Struct.new(:opts)
 
+    DESCRIPTION =
+      "Class definitions require explanatory comments on preceeding line"
+
     def self.key; :doc; end
     def self.name; "documentation checking"; end
     def self.options
@@ -39,7 +42,7 @@ module Cane
             file:        file_name,
             line:        number + 1,
             label:       extract_class_name(line),
-            description: "Classes are not documented"
+            description: DESCRIPTION
           }
         end
         last_line = line
@@ -60,7 +63,7 @@ module Cane
     end
 
     def extract_class_name(line)
-      line.match(/class ([^\s;]+)/)[1]
+      line.match(/class\s+([^\s;]+)/)[1]
     end
 
     def worker

data/lib/cane/version.rb

@@ -1,3 +1,3 @@
 module Cane
-  VERSION = '2.2.2'
+  VERSION = '2.2.3'
 end

data/spec/abc_check_spec.rb

@@ -7,6 +7,20 @@ describe Cane::AbcCheck do
     described_class.new(opts.merge(abc_glob: file_name))
   end
 
+  it 'does not create violations when no_abc flag is set' do
+    file_name = make_file(<<-RUBY)
+      class Harness
+        def complex_method(a)
+          b = a
+          return b if b > 3
+        end
+      end
+    RUBY
+
+    violations = check(file_name, abc_max: 1, no_abc: true).violations
+    violations.should be_empty
+  end
+
   it 'creates an AbcMaxViolation for each method above the threshold' do
     file_name = make_file(<<-RUBY)
       class Harness
@@ -21,7 +35,7 @@ describe Cane::AbcCheck do
       end
     RUBY
 
-    violations = check(file_name, abc_max: 1).violations
+    violations = check(file_name, abc_max: 1, no_abc: false).violations
     violations.length.should == 1
     violations[0].values_at(:file, :label, :value).should ==
       [file_name, "Harness#complex_method", 2]

data/spec/cane_spec.rb

@@ -49,7 +49,7 @@ describe 'The cane application' do
       --unhappy-file #{fn}
     )
     output.should include("Lines violated style requirements")
-    output.should include("Classes are not documented")
+    output.should include("Class definitions require explanatory comments")
     output.should include("Methods exceeded maximum allowed ABC complexity")
     exitstatus.should == 1
   end

data/spec/doc_check_spec.rb

@@ -11,8 +11,9 @@ describe Cane::DocCheck do
     file_name = make_file <<-RUBY
 # This class is documented
 class Doc; end
-class NoDoc; end # No doc
+class  NoDoc; end # No doc
   class AlsoNoDoc; end
+classIgnore = nil
 [:class]
 # class Ignore
 class Meta

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cane
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-30 00:00:00.000000000 Z
+date: 2012-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parallel