yard-contracts 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bf8df24a7341f6f8f5fcc55fc3edc99724ea38a
-  data.tar.gz: cb3ec2d3b9d4f013784e0a69a0c31e0deb70b2a4
+  metadata.gz: 51d85c2afe33dd7f5aa247c1731704b2b78123bc
+  data.tar.gz: 81c3ea5834a91fd1af549dae5d849b69218b2c5d
 SHA512:
-  metadata.gz: 499b2df5a4dd04103d8c94e557eb9ad9d9234b0286960e8be3939a64522440d6d6481264725f8bdd6eb2efcdef445df54970f4d2d263f6481a4c37e26d35458e
-  data.tar.gz: b3b2f541a12c1c861afde7b4823512a802f66e68c5f4dd45485641f493c55bc8793aae21e57449b233def0664327975024593b2f8691e1f4c45e9c9ea376e823
+  metadata.gz: 0a67e1b2c71f0343c07b17a796b2d8eac4928eb45976afdf31ea61267e430f6a859601a2aad286e0cca8758458cfc84552c107dd6e1a5869b0cb284854a94ef5
+  data.tar.gz: 507927641c2f838c3ec02aaf471bc4377ceae251a0cb137b59ae8f8633e2626417aa6e8c7071cd035a466efea71c41fe2104a3461437e6a402799014e0f712c5

data/.travis.yml

@@ -3,5 +3,6 @@ rvm:
   - 2.2.1
   - 2.1
   - 2.0
+  - 1.9.3
   - jruby-19mode
 script: bundle exec rspec

data/README.md

@@ -1,10 +1,12 @@
 # yard-contracts
 
-[![Build Status](https://travis-ci.org/sfcgeorge/yard-contracts.svg?branch=master)](https://travis-ci.org/sfcgeorge/yard-contracts)
 [![Gem Version](https://badge.fury.io/rb/yard-contracts.svg)](http://badge.fury.io/rb/yard-contracts)
+[![Code Climate](https://codeclimate.com/github/sfcgeorge/yard-contracts/badges/gpa.svg)](https://codeclimate.com/github/sfcgeorge/yard-contracts)
+[![Build Status](https://travis-ci.org/sfcgeorge/yard-contracts.svg?branch=master)](https://travis-ci.org/sfcgeorge/yard-contracts)
+[![Inline docs](http://inch-ci.org/github/sfcgeorge/yard-contracts.svg?branch=master)](http://inch-ci.org/github/sfcgeorge/yard-contracts)
 [![Join the chat at https://gitter.im/egonSchiele/contracts.ruby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/egonSchiele/contracts.ruby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-yard-contracts is a YARD plugin that works with the fantastic Contracts gem to automatically document types and descriptions of parameters in your method signatures, saving time, making your code concise and keeping your documentation consistent.
+yard-contracts is a YARD plugin that works with the fantastic [Contracts](https://github.com/egonSchiele/contracts.ruby) gem to automatically document types and descriptions of parameters in your method signatures, saving time, making your code concise and keeping your documentation consistent.
 
 Have you ever got fed up of coding validations, writing error messages and then documenting those things? All this duplication and boilerplate code has always bugged me. Contracts solves the validations and error messages part already, turning many lines of repetitive code into 1 terse readable one. This extension now solves the documentation part making documentation automatically say the same as your validations.
 

data/lib/yard-contracts.rb

@@ -1,5 +1,2 @@
-require "yard-contracts/version"
+require 'yard-contracts/version'
 require File.join(File.dirname(__FILE__), 'yard-contracts', 'contract_handler')
-
-module YARDContracts
-end

data/lib/yard-contracts/contract_handler.rb

@@ -8,12 +8,13 @@ require 'yard'
 require 'contracts/builtin_contracts'
 require 'yard-contracts/formatters'
 
-# Run the plugin handler by supplying it to yard with the --plugin flag, e.g.
+# Run the plugin handler by supplying it to yard with the --plugin flag
 #
-# bundle exec yardoc --plugin contracts
+# @example
+#   bundle exec yardoc --plugin contracts
 class ContractHandler < YARD::Handlers::Ruby::Base
   handles method_call(:Contract)
-  namespace_only #only match method calls inside a namespace not inside a method
+  namespace_only # only match calls inside a namespace not inside a method
 
   def process
     # statement is a YARD attribute, subclassing YARD::Parser::Ruby::AstNode
@@ -27,7 +28,7 @@ class ContractHandler < YARD::Handlers::Ruby::Base
     # Note: this won't document dynamicly defined methods.
     parent = statement.parent
     contract_last_line = statement.line_range.last
-    #YARD::Parser::Ruby::MethodDefinitionNode
+    # YARD::Parser::Ruby::MethodDefinitionNode
     def_method_ast = parent.traverse do |node|
       # Find the first def statement that comes after the contract we're on
       break node if node.line > contract_last_line && node.def?
@@ -37,48 +38,74 @@ class ContractHandler < YARD::Handlers::Ruby::Base
     ## TODO: What about module methods? Probably broken.
     scope = def_method_ast.source.match(/ self\./) ? :class : :instance
     name = def_method_ast.method_name true
-    params = def_method_ast.parameters #YARD::Parser::Ruby::ParameterNode
-    contracts = statement.parameters #YARD::Parser::Ruby::AstNode
+    params = def_method_ast.parameters # YARD::Parser::Ruby::ParameterNode
+    contracts = statement.parameters # YARD::Parser::Ruby::AstNode
 
     ret = Contracts::Formatters::ParamContracts.new(params, contracts).return
     params = Contracts::Formatters::ParamContracts.new(params, contracts).params
-    docstring = YARD::DocstringParser.new.parse(statement.docstring).to_docstring
+    doc = YARD::DocstringParser.new.parse(statement.docstring).to_docstring
 
+    process_params(doc, params)
+    process_return(doc, ret)
+
+    # YARD hasn't got to the def method yet, so we create a stub of it with
+    # our docstring, when YARD gets to it properly it will fill in the rest.
+    YARD::CodeObjects::MethodObject.new(namespace, name, scope) do |o|
+      o.docstring = doc
+    end
+    # No `register()` it breaks stuff! Above implicit return value is enough.
+  end
+
+  def process_params(doc, params)
+    merge_params(doc, params)
+    new_params(doc, params)
+  end
+
+  def merge_params(doc, params)
     # Merge params into provided docstring otherwise there can be duplicates
-    docstring.tags(:param).each do |tag|
-      param = params.find{ |t| t[0].to_s == tag.name.to_s }
-      if param
-        params.delete(param)
-        tag.types ||= []
-        tag.types << param[1].inspect
-        tag.text = "#{param[2].empty? ? '' : "#{param[2]}. "}#{tag.text}"
-      end
+    doc.tags(:param).each do |tag|
+      next unless (param = params.find { |t| t[0].to_s == tag.name.to_s })
+      params.delete(param)
+      set_tag(tag, param[1], param[2])
     end
+  end
+
+  def new_params(doc, params)
     # If the docstring didn't contain all of the params already add the rest
     params.each do |param|
-      docstring.add_tag(
+      doc.add_tag(
         YARD::Tags::Tag.new(:param, param[2].to_s, param[1].inspect, param[0])
       )
     end
+  end
 
-    # Merge return into provided docstring otherwise there can be a duplicate
-    # NOTE: Think about what to do with multiple returns
-    if (tag = docstring.tag(:return))
-      tag.types ||= []
-      tag.types << ret[0].inspect
-      tag.text = "#{ret[1].empty? ? '' : "#{ret[1]}. "}#{tag.text}"
+  def process_return(doc, ret)
+    if (tag = doc.tag :return)
+      # Merge return into provided docstring otherwise there can be a duplicate
+      merge_return(tag, ret)
     else
       # If the docstring didn't contain a return already add it
-      docstring.add_tag(
-        YARD::Tags::Tag.new(:return, ret[1].to_s, ret[0].inspect)
-      )
+      new_return(doc, ret)
     end
+  end
 
-    # YARD hasn't got to the def method yet, so we create a stub of it with
-    # our docstring, when YARD gets to it properly it will fill in the rest.
-    YARD::CodeObjects::MethodObject.new(namespace, name, scope) do |o|
-      o.docstring = docstring
-    end
-    # No `register()` it breaks stuff! Above implicit return value is enough.
+  def merge_return(tag, ret)
+    set_tag(tag, ret[0], ret[1])
+  end
+
+  def new_return(doc, ret)
+    doc.add_tag(
+      YARD::Tags::Tag.new(:return, ret[1].to_s, ret[0].inspect)
+    )
+  end
+
+  def set_tag(tag, type, to_s)
+    tag.types ||= []
+    tag.types << type.inspect
+    tag.text = tag_text(to_s, tag.text)
+  end
+
+  def tag_text(to_s, text)
+    "#{to_s.empty? ? '' : "#{to_s}. "}#{text}"
   end
 end

data/lib/yard-contracts/formatters.rb

@@ -5,7 +5,7 @@ module Contracts
   module Formatters
     # Used to format contracts for the `Expected:` field of error output.
     class Expected
-      def initialize(contract, full=true)
+      def initialize(contract, full = true)
         @contract, @full = contract, full
       end
 
@@ -23,22 +23,22 @@ module Contracts
       # Formats Hash contracts.
       def hash_contract(hash)
         @full = true
-        hash.inject({}) { |repr, (k, v)|
+        hash.inject({}) do |repr, (k, v)|
           repr.merge(k => InspectWrapper.new(contract(v), @full))
-        }.inspect
+        end.inspect
       end
 
       # Formats Array contracts.
       def array_contract(array)
         @full = true
-        array.map{ |v| InspectWrapper.new(contract(v), @full) }.inspect
+        array.map { |v| InspectWrapper.new(contract(v), @full) }.inspect
       end
     end
 
     # A wrapper class to produce correct inspect behaviour for different
     # contract values - constants, Class contracts, instance contracts etc.
     class InspectWrapper
-      def initialize(value, full=true)
+      def initialize(value, full = true)
         @value, @full = value, full
       end
 
@@ -51,7 +51,7 @@ module Contracts
         return '' unless full?
         return @value.inspect if empty_val?
         return @value.to_s if plain?
-        return delim(@value.to_s) if has_useful_to_s?
+        return delim(@value.to_s) if useful_to_s?
         @value.inspect.gsub(/^Contracts::/, '')
       end
 
@@ -65,14 +65,15 @@ module Contracts
       end
 
       private
+
       def empty_val?
-        @value.nil? || @value == ""
+        @value.nil? || @value == ''
       end
 
       def full?
         @full ||
-        @value.is_a?(Hash) || @value.is_a?(Array) ||
-        (!plain? && has_useful_to_s?)
+          @value.is_a?(Hash) || @value.is_a?(Array) ||
+          (!plain? && useful_to_s?)
       end
 
       def plain?
@@ -80,10 +81,14 @@ module Contracts
         !@value.is_a?(CallableClass) && @value.class != Class
       end
 
-      def has_useful_to_s?
+      def useful_to_s?
         # Useless to_s value or no custom to_s behavious defined
-        # Ruby < 2.0 makes inspect call to_s so this won't work
-        @value.to_s != "" && @value.to_s != @value.inspect
+        @value.to_s != '' &&
+          if @value.class == Class # It's a class contract
+            @value.to_s != @value.name
+          else # It's an instance contract
+            !@value.to_s.match(/#\<\w+:.+\>/)
+          end
       end
     end
 
@@ -95,7 +100,7 @@ module Contracts
       def to_a
         types = []
         @types.each_with_index do |type, i|
-          if i == @types.length-1
+          if i == @types.length - 1
             # Get the param out of the `param => result` part
             types << [type.first.first.source, type.first.first]
           else
@@ -118,8 +123,8 @@ module Contracts
 
       def to_a
         params = []
-        @params.each_with_index do |param, i|
-          #YARD::Parser::Ruby::AstNode
+        @params.each do |param|
+          # YARD::Parser::Ruby::AstNode
           next if param.nil?
           if param.type == :list
             param.each do |p|
@@ -134,6 +139,7 @@ module Contracts
       end
 
       private
+
       def build_param_element(param)
         type = param.type
         ident = param.jump(:ident, :label).last.to_sym
@@ -163,7 +169,8 @@ module Contracts
         # which are key value pairs of the Hash and build from that.
         result = {}
         hash.each do |h|
-          result[h[0].jump(:label).last.to_sym] = Contracts::Formatters::InspectWrapper.new(type(h[1]))
+          result[h[0].jump(:label).last.to_sym] =
+            Contracts::Formatters::InspectWrapper.new(type(h[1]))
         end
         result
       end
@@ -171,7 +178,9 @@ module Contracts
       # Formats Array type.
       def array_type(array)
         # This works because Ast inherits from Array.
-        array.map{ |v| Contracts::Formatters::InspectWrapper.new(type(v)) }.inspect
+        array.map do |v|
+          Contracts::Formatters::InspectWrapper.new(type(v))
+        end.inspect
       end
     end
 
@@ -190,7 +199,7 @@ module Contracts
           param_type, param = param
 
           on_named = param_type == :named_arg ||
-                    (named_count > 0 && param_type == :ident)
+                     (named_count > 0 && param_type == :ident)
           i -= named_count if on_named
 
           type, type_ast = @types[i]
@@ -240,18 +249,15 @@ module Contracts
       end
 
       private
+
       # The contract starts as a string, but we need to get it's real value
       # so that we can call to_s on it.
       def get_contract_value(type)
         con = type
         begin
           con = Contracts.const_get(type)
-        rescue Exception #NameError
-          begin
-            con = eval(type)
-          rescue Exception
-            con
-          end
+        rescue StandardError # NameError
+          con = eval(type) rescue StandardError
         end
         con
       end

data/lib/yard-contracts/version.rb

@@ -1,3 +1,3 @@
 module YARDContracts
-  VERSION = "0.1.1"
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-contracts
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Simon George
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-28 00:00:00.000000000 Z
+date: 2015-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard