yard-heuristics 1.1.0 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2ef6b420a250a2fdfea079c60c2fcc989606c887
+  data.tar.gz: 10858faf20695c998243c94e2b92f4d4e2d4e7b8
+SHA512:
+  metadata.gz: bb2f1c75cafee7dee1e602ed5f7f5aa113e2510c9560cbb408ccc273a73a56efb38a9fb5de3cedc87b23634b74ef2a2c3b77da3380469ad26bcd493b92d93dfd
+  data.tar.gz: a64b570b41ab01e735dbf4838ca6fae4752db49c416336f0a9ec1cb698945c6f2ea5e3199d151eaef0dfd23dc31ead7db82ee59d164be9b35579623639204cca

data/README

@@ -1,4 +1,177 @@
                                   YARD-Heuristics
 
   YARD-Heuristics heuristically determines types of parameters and return
-  values to YARD.
+  values for YARD documentation that doesn’t explicitly document it.  This
+  allows you to write documentation that isn’t adorned with “obvious” types,
+  but still get that information into the output.  It also lets you
+  nice-looking references to parameters and have them be marked up
+  appropriately in HTML output.
+
+§ Heuristics
+
+    The following sections list the various heuristics that YARD-Heuristics
+    apply for determining types of parameters and return values.
+
+    Note that for all heuristics, a type will only be added if none already
+    exists.
+
+  § Parameter Named “other”
+
+      A parameter named “other” has the same type as the receiver.  This turns
+
+        class Point
+          def ==(other)
+
+      into
+
+        class Point
+          # @param [Point] other
+          def ==(other)
+
+  § Parameter Types Derived by Parameter Name
+
+      Parameters to a method with names in the following table has the type
+      listed on the same row.
+
+    | Name   | Type      |
+    |--------+-----------|
+    | index  | [Integer] |
+    | object | [Object]  |
+    | range  | [Range]   |
+    | string | [String]  |
+
+      Thus
+
+        class Point
+          def x_inside?(range)
+
+      becomes
+
+        class Point
+          # @param [Range] range
+          def x_inside?(range)
+
+  § Block Parameters
+
+      If the last parameter to a method’s name begins with ‘&’ it has the type
+      [Proc].
+
+        class Method
+          def initialize(&block)
+
+      becomes
+
+        class Method
+          # @param [Block] block
+          def initialize(&block)
+
+  § Return Types by Method Name
+
+      For the return type of a method with less than two ‹@return› tags, the
+      method name is lookup up in the following table and has the type listed on
+      the same row. For the “type” “self or type”, if a ‹@param› tag exists with
+      the name “other”, the type of the receiver is used, otherwise “self” is
+      used.  For the “type” “type”, the type of the receiver is used.
+
+    | Name            | Type           |
+    |-----------------+----------------|
+    | ‹<<›            | self or type   |
+    | ‹>>›            | self or type   |
+    | ‹==›            | [Boolean]      |
+    | ‹===›           | [Boolean]      |
+    | ‹=~›            | [Boolean]      |
+    | ‹<=>›           | [Integer, nil] |
+    | ‹+›             | type           |
+    | ‹-›             | type           |
+    | ‹*›             | type           |
+    | ‹/›             | type           |
+    | each            | [self]         |
+    | each_with_index | [self]         |
+    | hash            | [Integer]      |
+    | inspect         | [String]       |
+    | length          | [Integer]      |
+    | size            | [Integer]      |
+    | to_s            | [String]       |
+    | to_str          | [String]       |
+
+
+      Thus
+
+        class Point
+          def <<(other)
+
+      becomes
+
+        class Point
+          # @return [Point]
+          def <<(other)
+
+      but
+
+        class List
+          def <<(item)
+
+      becomes
+
+        class List
+          # @return [self]
+          def <<(item)
+
+§ Emphasizing Parameter Names
+
+    When producing HTML output, any words in all uppercase, with a possible
+    “th” suffix, that is also the name of a parameter, an ‹@option›, or a
+    ‹@yieldparam›, will be downcased and emphasized with a class of
+    “parameter”.
+
+    In the following example, “OTHER” will be turned into
+    ‹<em class="parameter">other</em>›:
+
+      class Point
+        # @return True if the receiver’s class and {#x} and {#y} `#==` those of
+        #   OTHER
+        def ==(other)
+
+§ Usage
+
+    Add ‹--plugin yard-heuristics-1.0› to your YARD command line.  If you’re
+    using Inventory-Rake-Tasks-YARD¹, add the following to your Rakefile:
+
+      Inventory::Rake::Tasks::YARD.new do |t|
+        t.options += %w'--plugin yard-heuristics-1.0'
+      end
+
+¹ See http://disu.se/software/inventory-rake-tasks-yard/
+
+§ API
+
+    There’s really not very much to the YARD-Heuristics API.  What you can do
+    is add (or modify) the types of parameters and return types of methods by
+    adding (or modifying) entries in the Hash tables
+    ‹YARDHeuristics::ParamTypes› and ‹YARDHeuristics::ReturnTypes›
+    respectively.  That’s about it.
+
+§ Financing
+
+    Currently, most of my time is spent at my day job and in my rather busy
+    private life.  Please motivate me to spend time on this piece of software
+    by donating some of your money to this project.  Yeah, I realize that
+    requesting money to develop software is a bit, well, capitalistic of me.
+    But please realize that I live in a capitalistic society and I need money
+    to have other people give me the things that I need to continue living
+    under the rules of said society.  So, if you feel that this piece of
+    software has helped you out enough to warrant a reward, please PayPal a
+    donation to now@disu.se¹.  Thanks!  Your support won’t go unnoticed!
+
+¹ Send a donation:
+  https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=now%40disu%2ese&item_name=Nikolai%20Weibull%20Software%20Services
+
+§ Reporting Bugs
+
+    Please report any bugs that you encounter to the {issue tracker}¹.
+
+  ¹ See https://github.com/now/yard-heuristics/issues
+
+§ Authors
+
+    Nikolai Weibull wrote the code, the tests, and this README.

data/Rakefile

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 
-require 'inventory/rake-1.0'
+require 'inventory-rake-1.0'
 
-load File.expand_path('../lib/yard-heuristics/version.rb', __FILE__)
+load File.expand_path('../lib/yard-heuristics-1.0/version.rb', __FILE__)
 
 Inventory::Rake::Tasks.define YARDHeuristics::Version, :gem => proc{ |_, s|
   s.author = 'Nikolai Weibull'
@@ -11,7 +11,7 @@ Inventory::Rake::Tasks.define YARDHeuristics::Version, :gem => proc{ |_, s|
 }
 
 Inventory::Rake::Tasks.unless_installing_dependencies do
-  require 'lookout/rake-3.0'
+  require 'lookout-rake-3.0'
   # TODO: Silence warnings generated from YARD (remove this once we plug them)
   Lookout::Rake::Tasks::Test.new :options => []
 end

data/lib/yard-heuristics-1.0.rb

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 
-# Namespace for YARD heuristics.
+# Namespace for YARD-Heuristics.
 module YARDHeuristics
-  load File.expand_path('../yard-heuristics/version.rb', __FILE__)
+  load File.expand_path('../yard-heuristics-1.0/version.rb', __FILE__)
   Version.load
 
   ParamTypes = {
@@ -111,8 +111,11 @@ module YARD::Templates::Helpers::HtmlHelper
       else
         parameter = $1.downcase
         ((object.parameters.assoc(parameter) ||
+          object.parameters.assoc(parameter + ':') ||
           object.parameters.assoc('*' + parameter) ||
+          object.parameters.assoc('**' + parameter) ||
           object.parameters.assoc('&' + parameter) ||
+          object.tags.find{ |e| e.tag_name == 'option' and e.pair.name == ':' + parameter } ||
           object.tags.find{ |e| e.tag_name == 'yieldparam' and e.name == parameter }) ?
          '<em class="parameter">%s</em>' % parameter :
          $1) + $2.to_s

data/lib/{yard-heuristics → yard-heuristics-1.0}/version.rb

@@ -3,10 +3,10 @@
 require 'inventory-1.0'
 
 module YARDHeuristics
-  Version = Inventory.new(1, 1, 0){
+  Version = Inventory.new(1, 2, 0){
     def dependencies
       super + Inventory::Dependencies.new{
-        development 'inventory-rake', 1, 3, 0
+        development 'inventory-rake', 1, 4, 0
         development 'lookout', 3, 0, 0
         development 'lookout-rake', 3, 0, 0
         runtime 'yard', 0, 8, 0, :feature => 'yard'

data/test/unit/yard-heuristics-1.0.rb

@@ -200,6 +200,31 @@ EOS
 # @yieldparam [Exception] exception
 def a
 end
+EOS
+    Module.new{
+      class << self
+        include YARD::Templates::Helpers::HtmlHelper
+        def options
+          YARD::Templates::TemplateOptions.new{ |o|
+            o.reset_defaults
+          }
+        end
+        def object
+          YARD::Registry.at('#a')
+        end
+      end
+    }.instance_eval{
+      htmlify(YARD::Registry.at('#a').docstring)
+    }
+  end
+
+  expect 'Yields the <em class="parameter">exception</em>.' do
+    YARD::Registry.clear
+    YARD::Parser::SourceParser.parse_string(<<EOS)
+# Yields the EXCEPTION.
+# @option options [Exception] :exception
+def a(options = {})
+end
 EOS
     Module.new{
       class << self

metadata

@@ -1,82 +1,272 @@
 --- !ruby/object:Gem::Specification
 name: yard-heuristics
 version: !ruby/object:Gem::Version
-  version: 1.1.0
-  prerelease: 
+  version: 1.2.0
 platform: ruby
 authors:
 - Nikolai Weibull
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-03 00:00:00.000000000 Z
+date: 2013-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inventory
-  requirement: &15442740 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *15442740
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: inventory-rake
-  requirement: &15441408 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
   type: :development
   prerelease: false
-  version_requirements: *15441408
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: lookout
-  requirement: &15440268 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
-  version_requirements: *15440268
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: lookout-rake
-  requirement: &15438504 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
-  version_requirements: *15438504
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &15436296 !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.8.0
   type: :runtime
   prerelease: false
-  version_requirements: *15436296
-description: ! "                                  YARD-Heuristics\n\n  YARD-Heuristics
-  heuristically determines types of parameters and return\n  values to YARD.\n"
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+description: |2
+                                    YARD-Heuristics
+
+    YARD-Heuristics heuristically determines types of parameters and return
+    values for YARD documentation that doesn’t explicitly document it.  This
+    allows you to write documentation that isn’t adorned with “obvious” types,
+    but still get that information into the output.  It also lets you
+    nice-looking references to parameters and have them be marked up
+    appropriately in HTML output.
+
+  § Heuristics
+
+      The following sections list the various heuristics that YARD-Heuristics
+      apply for determining types of parameters and return values.
+
+      Note that for all heuristics, a type will only be added if none already
+      exists.
+
+    § Parameter Named “other”
+
+        A parameter named “other” has the same type as the receiver.  This turns
+
+          class Point
+            def ==(other)
+
+        into
+
+          class Point
+            # @param [Point] other
+            def ==(other)
+
+    § Parameter Types Derived by Parameter Name
+
+        Parameters to a method with names in the following table has the type
+        listed on the same row.
+
+      | Name   | Type      |
+      |--------+-----------|
+      | index  | [Integer] |
+      | object | [Object]  |
+      | range  | [Range]   |
+      | string | [String]  |
+
+        Thus
+
+          class Point
+            def x_inside?(range)
+
+        becomes
+
+          class Point
+            # @param [Range] range
+            def x_inside?(range)
+
+    § Block Parameters
+
+        If the last parameter to a method’s name begins with ‘&’ it has the type
+        [Proc].
+
+          class Method
+            def initialize(&block)
+
+        becomes
+
+          class Method
+            # @param [Block] block
+            def initialize(&block)
+
+    § Return Types by Method Name
+
+        For the return type of a method with less than two ‹@return› tags, the
+        method name is lookup up in the following table and has the type listed on
+        the same row. For the “type” “self or type”, if a ‹@param› tag exists with
+        the name “other”, the type of the receiver is used, otherwise “self” is
+        used.  For the “type” “type”, the type of the receiver is used.
+
+      | Name            | Type           |
+      |-----------------+----------------|
+      | ‹<<›            | self or type   |
+      | ‹>>›            | self or type   |
+      | ‹==›            | [Boolean]      |
+      | ‹===›           | [Boolean]      |
+      | ‹=~›            | [Boolean]      |
+      | ‹<=>›           | [Integer, nil] |
+      | ‹+›             | type           |
+      | ‹-›             | type           |
+      | ‹*›             | type           |
+      | ‹/›             | type           |
+      | each            | [self]         |
+      | each_with_index | [self]         |
+      | hash            | [Integer]      |
+      | inspect         | [String]       |
+      | length          | [Integer]      |
+      | size            | [Integer]      |
+      | to_s            | [String]       |
+      | to_str          | [String]       |
+
+
+        Thus
+
+          class Point
+            def <<(other)
+
+        becomes
+
+          class Point
+            # @return [Point]
+            def <<(other)
+
+        but
+
+          class List
+            def <<(item)
+
+        becomes
+
+          class List
+            # @return [self]
+            def <<(item)
+
+  § Emphasizing Parameter Names
+
+      When producing HTML output, any words in all uppercase, with a possible
+      “th” suffix, that is also the name of a parameter, an ‹@option›, or a
+      ‹@yieldparam›, will be downcased and emphasized with a class of
+      “parameter”.
+
+      In the following example, “OTHER” will be turned into
+      ‹<em class="parameter">other</em>›:
+
+        class Point
+          # @return True if the receiver’s class and {#x} and {#y} `#==` those of
+          #   OTHER
+          def ==(other)
+
+  § Usage
+
+      Add ‹--plugin yard-heuristics-1.0› to your YARD command line.  If you’re
+      using Inventory-Rake-Tasks-YARD¹, add the following to your Rakefile:
+
+        Inventory::Rake::Tasks::YARD.new do |t|
+          t.options += %w'--plugin yard-heuristics-1.0'
+        end
+
+  ¹ See http://disu.se/software/inventory-rake-tasks-yard/
+
+  § API
+
+      There’s really not very much to the YARD-Heuristics API.  What you can do
+      is add (or modify) the types of parameters and return types of methods by
+      adding (or modifying) entries in the Hash tables
+      ‹YARDHeuristics::ParamTypes› and ‹YARDHeuristics::ReturnTypes›
+      respectively.  That’s about it.
+
+  § Financing
+
+      Currently, most of my time is spent at my day job and in my rather busy
+      private life.  Please motivate me to spend time on this piece of software
+      by donating some of your money to this project.  Yeah, I realize that
+      requesting money to develop software is a bit, well, capitalistic of me.
+      But please realize that I live in a capitalistic society and I need money
+      to have other people give me the things that I need to continue living
+      under the rules of said society.  So, if you feel that this piece of
+      software has helped you out enough to warrant a reward, please PayPal a
+      donation to now@disu.se¹.  Thanks!  Your support won’t go unnoticed!
+
+  ¹ Send a donation:
+    https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=now%40disu%2ese&item_name=Nikolai%20Weibull%20Software%20Services
+
+  § Reporting Bugs
+
+      Please report any bugs that you encounter to the {issue tracker}¹.
+
+    ¹ See https://github.com/now/yard-heuristics/issues
+
+  § Authors
+
+      Nikolai Weibull wrote the code, the tests, and this README.
 email: now@bitwi.se
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/yard-heuristics-1.0.rb
-- lib/yard-heuristics/version.rb
+- lib/yard-heuristics-1.0/version.rb
 - test/unit/yard-heuristics-1.0.rb
-- test/unit/yard-heuristics/version.rb
+- test/unit/yard-heuristics-1.0/version.rb
 - README
 - Rakefile
 homepage: https://github.com/now/yard-heuristics
@@ -87,21 +277,19 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 2.0.0
 signing_key: 
 specification_version: 4
-summary: values to YARD.
+summary: values for YARD documentation that doesn’t explicitly document it.
 test_files: []