cane 2.2.2 → 2.2.3

Sign up to get free protection for your applications and to get access to all the features.
data/HISTORY.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Cane History
2
2
 
3
+ ## 2.2.3 - 3 September 2012 (e4fe90ee)
4
+
5
+ * Bugfix: Allow multiple spaces before class name. (#34)
6
+ * Bugfix: Remove wacky broken conditional in AbcCheck. (#33)
7
+ * Doc: Better guidance on class level comments. (#35)
8
+
3
9
  ## 2.2.2 - 29 August 2012 (3a9be454)
4
10
 
5
11
  * Bugfix: Stricter magic comment regex to avoid false positives (#31)
data/README.md CHANGED
@@ -24,7 +24,7 @@ a non-zero exit code if any quality checks fail. Also, a report:
24
24
  lib/cane.rb:20 Line length >80
25
25
  lib/cane.rb:42 Trailing whitespace
26
26
 
27
- Classes are not documented (1):
27
+ Class definitions require explanatory comments on preceeding line (1):
28
28
  lib/cane:3 SomeClass
29
29
 
30
30
  Customize behaviour with a wealth of options:
@@ -167,6 +167,31 @@ Or in your rake task:
167
167
  c.use UnhappyCheck, unhappy_file: 'myfile'
168
168
  end
169
169
 
170
+ ## Protips
171
+
172
+ ### Writing class level documentation
173
+
174
+ Classes are commonly the first entry point into a code base, often for an
175
+ oncall engineer responding to an exception, so provide enough information to
176
+ orient first-time readers.
177
+
178
+ A good class level comment should answer the following:
179
+
180
+ * Why does this class exist?
181
+ * How does it fit in to the larger system?
182
+ * Explanation of any domain-specific terms.
183
+
184
+ If you have specific documentation elsewhere (say, in the README or a wiki), a
185
+ link to that suffices.
186
+
187
+ If the class is a known entry point, such as a regular background job that can
188
+ potentially fail, then also provide enough context that it can be efficently
189
+ dealt with. In the background job case:
190
+
191
+ * Should it be retried?
192
+ * What if it failed 5 days ago and we're only looking at it now?
193
+ * Who cares that this job failed?
194
+
170
195
  ## Compatibility
171
196
 
172
197
  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
176
201
 
177
202
  ## Support
178
203
 
179
- [Ask questions on Stack
180
- Overflow](http://stackoverflow.com/questions/ask?tags=ruby+cane). We keep an
181
- eye on new cane questions.
204
+ Make a [new github issue](https://github.com/square/cane/issues/new).
182
205
 
183
206
  ## Contributing
184
207
 
@@ -33,7 +33,7 @@ module Cane
33
33
  end
34
34
 
35
35
  def violations
36
- return [] if opts[:no_abc] == false
36
+ return [] if opts[:no_abc]
37
37
 
38
38
  order worker.map(file_names) {|file_name|
39
39
  find_violations(file_name)
@@ -6,6 +6,9 @@ module Cane
6
6
  # comment immediately preceeding.
7
7
  class DocCheck < Struct.new(:opts)
8
8
 
9
+ DESCRIPTION =
10
+ "Class definitions require explanatory comments on preceeding line"
11
+
9
12
  def self.key; :doc; end
10
13
  def self.name; "documentation checking"; end
11
14
  def self.options
@@ -39,7 +42,7 @@ module Cane
39
42
  file: file_name,
40
43
  line: number + 1,
41
44
  label: extract_class_name(line),
42
- description: "Classes are not documented"
45
+ description: DESCRIPTION
43
46
  }
44
47
  end
45
48
  last_line = line
@@ -60,7 +63,7 @@ module Cane
60
63
  end
61
64
 
62
65
  def extract_class_name(line)
63
- line.match(/class ([^\s;]+)/)[1]
66
+ line.match(/class\s+([^\s;]+)/)[1]
64
67
  end
65
68
 
66
69
  def worker
data/lib/cane/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Cane
2
- VERSION = '2.2.2'
2
+ VERSION = '2.2.3'
3
3
  end
@@ -7,6 +7,20 @@ describe Cane::AbcCheck do
7
7
  described_class.new(opts.merge(abc_glob: file_name))
8
8
  end
9
9
 
10
+ it 'does not create violations when no_abc flag is set' do
11
+ file_name = make_file(<<-RUBY)
12
+ class Harness
13
+ def complex_method(a)
14
+ b = a
15
+ return b if b > 3
16
+ end
17
+ end
18
+ RUBY
19
+
20
+ violations = check(file_name, abc_max: 1, no_abc: true).violations
21
+ violations.should be_empty
22
+ end
23
+
10
24
  it 'creates an AbcMaxViolation for each method above the threshold' do
11
25
  file_name = make_file(<<-RUBY)
12
26
  class Harness
@@ -21,7 +35,7 @@ describe Cane::AbcCheck do
21
35
  end
22
36
  RUBY
23
37
 
24
- violations = check(file_name, abc_max: 1).violations
38
+ violations = check(file_name, abc_max: 1, no_abc: false).violations
25
39
  violations.length.should == 1
26
40
  violations[0].values_at(:file, :label, :value).should ==
27
41
  [file_name, "Harness#complex_method", 2]
data/spec/cane_spec.rb CHANGED
@@ -49,7 +49,7 @@ describe 'The cane application' do
49
49
  --unhappy-file #{fn}
50
50
  )
51
51
  output.should include("Lines violated style requirements")
52
- output.should include("Classes are not documented")
52
+ output.should include("Class definitions require explanatory comments")
53
53
  output.should include("Methods exceeded maximum allowed ABC complexity")
54
54
  exitstatus.should == 1
55
55
  end
@@ -11,8 +11,9 @@ describe Cane::DocCheck do
11
11
  file_name = make_file <<-RUBY
12
12
  # This class is documented
13
13
  class Doc; end
14
- class NoDoc; end # No doc
14
+ class NoDoc; end # No doc
15
15
  class AlsoNoDoc; end
16
+ classIgnore = nil
16
17
  [:class]
17
18
  # class Ignore
18
19
  class Meta
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: cane
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.2
4
+ version: 2.2.3
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2012-08-30 00:00:00.000000000 Z
12
+ date: 2012-09-03 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: parallel