yardstick 0.9.6 → 0.9.7

data/lib/yardstick/rules/example_tag.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+module Yardstick
+  module Rules
+    # Checks if method has @example tag
+    #
+    # This applies only for public methods
+    #
+    class ExampleTag < Rule
+      self.description = 'The public/semipublic method should have an example specified'
+
+      # @see class description
+      #
+      # @return [Boolean]
+      #   true if method is not private and it returns something meaningful
+      #
+      # @api private
+      def validatable?
+        !api?(%w[ private ]) && tag_types('return') != %w[ undefined ]
+      end
+
+      # @see class description
+      #
+      # @return [Boolean]
+      #   true if has example tag
+      #
+      # @api private
+      def valid?
+        has_tag?('example')
+      end
+    end
+  end
+end

data/lib/yardstick/rules/return_tag.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+module Yardstick
+  module Rules
+    # Checks if method has a @return tag
+    #
+    class ReturnTag < Rule
+      self.description = 'The @return tag should be specified'
+
+      # @see class description
+      #
+      # @return [Boolean]
+      #   true if has return tag
+      #
+      # @api private
+      def valid?
+        has_tag?('return')
+      end
+    end
+  end
+end

data/lib/yardstick/rules/summary.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+module Yardstick
+  module Rules
+    # Rules related to method summary
+    #
+    class Summary
+      # Checks if method summary is present
+      #
+      class Presence < Rule
+        self.description = 'The method summary should be specified'
+
+        # @see Rule::validatable?
+        #
+        # @return [Boolean]
+        #   true if method does not have @see tag
+        #
+        # @api private
+        def validatable?
+          !has_tag?('see')
+        end
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if summary text is not empty
+        #
+        # @api private
+        def valid?
+          !summary_text.empty?
+        end
+      end
+
+      # Checks that method summary length doesn't go over 80 characters
+      #
+      class Length < Rule
+        MAXIMUM_LINE_LENGTH = 80
+
+        self.description = 'The method summary should be less than 80 characters in length'
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if summary length is below 80 characters
+        #
+        # @api private
+        def valid?
+          summary_text.split(//u).count <= MAXIMUM_LINE_LENGTH
+        end
+      end
+
+      # Checks that method summary doesn't end with a period
+      #
+      class Delimiter < Rule
+        self.description = 'The method summary should not end in a period'
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if summary text does not end with a period
+        #
+        # @api private
+        def valid?
+          summary_text[-1, 1] != '.'
+        end
+      end
+
+      # Checks that method summary length is exactly one line
+      #
+      class SingleLine < Rule
+        LINE_BREAK_CHARACTER = "\n"
+
+        self.description = 'The method summary should be a single line'
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if summary text does not include a new line
+        #
+        # @api private
+        def valid?
+          !summary_text.include?(LINE_BREAK_CHARACTER)
+        end
+      end
+    end
+  end
+end

data/lib/yardstick/version.rb

@@ -3,6 +3,6 @@
 module Yardstick
 
   # Gem version
-  VERSION = '0.9.6'.freeze
+  VERSION = '0.9.7'.freeze
 
 end # module Yardstick

data/lib/yardstick/yard_ext.rb

@@ -4,13 +4,8 @@ module YARD  #:nodoc: all
 
   # Test if JRuby head is being used
   JRUBY_19MODE = RUBY_VERSION >= '1.9' && RUBY_ENGINE == 'jruby'
-  JRUBY_HEAD   = JRUBY_19MODE && JRUBY_VERSION >= '1.7.4.dev'
 
   # Fix jruby-head to use the ruby 1.8 parser until their ripper port is working
-  Parser::SourceParser.parser_type = :ruby18 if JRUBY_HEAD
+  Parser::SourceParser.parser_type = :ruby18 if JRUBY_19MODE
 
-  # Extend docstring with yardstick methods
-  class Docstring
-    include Yardstick::Method
-  end # class Docstring
 end # module YARD

data/spec/integration/yardstick/class_methods/measure_spec.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick, '.measure' do
+  describe 'with no arguments' do
+    before :all do
+      @measurements = Yardstick.measure
+    end
+
+    it_should_behave_like 'measured itself'
+  end
+
+  describe 'with a config' do
+    before :all do
+      config = Yardstick::Config.new(path: Yardstick::ROOT.join('lib', 'yardstick.rb'))
+      @measurements = Yardstick.measure(config)
+    end
+
+    it_should_behave_like 'measured itself'
+  end
+end

data/spec/integration/yardstick/class_methods/measure_string_spec.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick, '.measure_string' do
+  context 'with a string' do
+    subject { described_class.measure_string('def test; end') }
+
+    it { should be_a(Yardstick::MeasurementSet) }
+
+    it { should_not be_empty }
+  end
+
+  describe 'with no arguments' do
+    it 'should raise an exception' do
+      expect { Yardstick.measure_string }
+        .to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/integration/yardstick/document/file_spec.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick::Document, '#file' do
+  subject { described_class.new(docstring).file }
+
+  let(:docstring) { YARD::Registry.all(:method).first.docstring }
+  let(:file)      { Yardstick::ROOT.join('lib', 'yardstick.rb') }
+
+  before { YARD.parse([file.to_s], [], YARD::Logger::ERROR) }
+
+  it { should be_kind_of(Pathname) }
+
+  it { should == file }
+end

data/spec/integration/yardstick/document/line_spec.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick::Document, '#line' do
+  subject { described_class.new(docstring).line }
+
+  let(:docstring) { YARD::Registry.all(:method).first.docstring }
+
+  before do
+    YARD.parse_string(<<-RUBY)
+      module Foo
+        class Bar
+          # Instance method
+          #
+          # @api public
+          def baz(value)
+          end
+        end
+      end
+    RUBY
+  end
+
+  it { should be(6) }
+end

data/spec/integration/yardstick/document/path_spec.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick::Document, '#path' do
+  subject { described_class.new(docstring).path }
+
+  let(:docstring) { YARD::Registry.all(:method).first.docstring }
+
+  context 'when instance method' do
+    before do
+      YARD.parse_string(<<-RUBY)
+        module Foo
+          class Bar
+            # Instance method
+            #
+            # @api public
+            def baz(value)
+            end
+          end
+        end
+      RUBY
+    end
+
+    it { should == 'Foo::Bar#baz' }
+  end
+
+  context 'when class method' do
+    before do
+      YARD.parse_string(<<-RUBY)
+        module Foo
+          class Bar
+            # Instance method
+            #
+            # @api public
+            def self.baz(value)
+            end
+          end
+        end
+      RUBY
+    end
+
+    it { should == 'Foo::Bar.baz' }
+  end
+end

data/spec/integration/yardstick/processor/process_string_spec.rb

@@ -0,0 +1,401 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Yardstick::Document, '#process_string' do
+  subject(:measurements) { processor.process_string(method) }
+
+  let(:processor) { Yardstick::Processor.new(config) }
+  let(:config)    { Yardstick::Config.new            }
+
+  let(:valid_method) do
+    (<<-RUBY)
+      # This is a method summary that is the maximum --- exactly 80 characters in length
+      #
+      # @example
+      #   test('Hello World')  # => nil
+      #
+      # @param [#to_str] value
+      #   the value
+      #
+      # @return [nil]
+      #   returns nil
+      #
+      # @api public
+      def test(value)
+      end
+    RUBY
+  end
+
+  def measurement(description)
+    measurements.detect do |measurement|
+      measurement.description == description
+    end
+  end
+
+  describe 'with a method summary' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The method summary should be specified')).to be_ok
+    end
+  end
+
+  describe 'without a method summary' do
+    let(:method) { 'def test(value); end' }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The method summary should be specified')).to_not be_ok
+    end
+  end
+
+  describe 'without a method summary when validations are turned off' do
+    let(:config) do
+      Yardstick::Config.new(rules: {
+        'Summary::Presence'.to_sym => { enabled: false }
+      })
+    end
+    let(:method) { 'def test(value); end' }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The method summary should be specified')).to be_ok
+    end
+  end
+
+  describe 'without a method summary when validations are turned off for given class' do
+    let(:config) do
+      Yardstick::Config.new(rules: {
+        'Summary::Presence'.to_sym => { enabled: true, exclude: %w[World] }
+      })
+    end
+    let(:method) { 'class World; def test(value); end; end' }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurements.detect { |measurement| measurement.description == 'The method summary should be specified' }).to be_ok
+    end
+  end
+
+  describe 'with a method summary that is 80 characters in length' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The method summary should be less than 80 characters in length'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method summary that is 81 characters in length' do
+    let(:method) do
+      (<<-RUBY)
+        # This is a method summary greater than the maximum - it is 81 characters in length
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The method summary should be less than 80 characters in length'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a method summary that does not end in a period' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The method summary should not end in a period'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method summary that does end in a period' do
+    let(:method) do
+      <<-RUBY
+        # This method summary ends in a period.
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The method summary should not end in a period'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a method summary that is on one line' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The method summary should be a single line'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method summary that is not on one line' do
+    let(:method) do
+      <<-RUBY
+        # This method summary
+        # is on two lines
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The method summary should be a single line'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a method that has an @example tag' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The public/semipublic method should have an example specified'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method that is private' do
+    let(:method) do
+      <<-RUBY
+        # @api private
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should be skipped' do
+      expect(measurement('The public/semipublic method should have an example specified'))
+        .to be_skip
+    end
+  end
+
+  describe 'with a method that does not have an @example tag, and has an undefined @return tag' do
+    let(:method) do
+      <<-RUBY
+        # @return [undefined]
+        #
+        # @api public
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should be skipped' do
+      expect(measurement('The public/semipublic method should have an example specified'))
+        .to be_skip
+    end
+  end
+
+  describe 'with a method that has an @api tag' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The @api tag should be specified'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method that does not have an @api tag' do
+    let(:method) { 'def test(value); end' }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The @api tag should be specified'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a method that has a public @api tag' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The @api tag must be either public, semipublic or private'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a method that has an invalid @api tag' do
+    let(:method) do
+      <<-RUBY
+        # @api invalid
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The @api tag must be either public, semipublic or private'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a protected method and a semipublic @api tag' do
+    let(:method) do
+      <<-RUBY
+        protected
+
+        # @api semipublic
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('A method with protected visibility must have an @api tag of semipublic or private'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a protected method and a private @api tag' do
+    let(:method) do
+      <<-RUBY
+        protected
+
+        # @api private
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('A method with protected visibility must have an @api tag of semipublic or private'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a protected method and a public @api tag' do
+    let(:method) do
+      <<-RUBY
+        protected
+
+        # @api public
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('A method with protected visibility must have an @api tag of semipublic or private'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a private method and a private @api tag' do
+    let(:method) do
+      <<-RUBY
+        private
+
+        # @api private
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('A method with private visibility must have an @api tag of private'))
+        .to be_ok
+    end
+  end
+
+  describe 'with a private method and a public @api tag' do
+    let(:method) do
+      <<-RUBY
+        private
+
+        # @api public
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('A method with private visibility must have an @api tag of private'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a private method and a semipublic @api tag' do
+    let(:method) do
+      <<-RUBY
+        private
+
+        # @api semipublic
+        def test(value)
+        end
+      RUBY
+    end
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('A method with private visibility must have an @api tag of private'))
+        .to_not be_ok
+    end
+  end
+
+  describe 'with a method that has a @return tag' do
+    let(:method) { valid_method }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have a correct measurement' do
+      expect(measurement('The @return tag should be specified')).to be_ok
+    end
+  end
+
+  describe 'with a method that does not have a @return tag' do
+    let(:method) { 'def test(value); end' }
+
+    it { should be_kind_of(Yardstick::MeasurementSet) }
+
+    it 'should have an incorrect measurement' do
+      expect(measurement('The @return tag should be specified')).to_not be_ok
+    end
+  end
+end