yard-bench 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 !binary "U0hBMQ==":
-  metadata.gz: f4b741f7ac917188402ae134a53b8ee9f65a4409
-  data.tar.gz: a6db99b9f15facdd66aabd7936176681a0259caa
+  metadata.gz: 9e8567b9d6ef87a15a4c3c01bd809a9bae49e42c
+  data.tar.gz: 79aafe9d2e453c7838c53a65b7912834d2791f21
 !binary "U0hBNTEy":
-  metadata.gz: 4c3359d6aaf319af83c779c4998aa438f5ed846b69335a6b6a1082e3eb19450f30cf9f6e2b237cb11d3b004d44f77facc265132ffc54775b2c63e02dc228a894
-  data.tar.gz: 22637cfe552421e8bf4d11bb1fd1817a84b27fe7ad2568eb1b6dfc7d589680322935b8e4e7ad1cba61da41b857454afc3330388db48b87b3dd16d94fb8d1a3af
+  metadata.gz: 50999cac89d2fa786c7f852e858620328f7ffec57ee4e21f46e18665e79d55230f7a3ef7b6240043dfc1eda42b79842841bf9e3c7904bd6a26e2c19a5787c5e7
+  data.tar.gz: cc4396f9a4af167123ab2f046ecdb7b0014c4c3e71cc41faedf5ab321687f147fe6bc53da2686bc0007d4ba864c5e2129f90ccb29cdac5648b10e2f214ca135e

data/README.md

@@ -1,6 +1,81 @@
 # YARD::Bench
 
-TODO: Write a gem description
+Lazy benchmarking of your project, which appears in the generated [YARD](http://yardoc.org/) documentation.
+There is a handy DSL provided to make benchmarking almost without additional effort.
+
+To mark a method(s) for benchmarking, just put
+
+```ruby
+benchmark :meth1, :meth2
+```
+
+or
+
+    ⌚ :meth1, :meth2
+    
+or even
+
+```ruby
+benchmark :⋅
+```
+
+somewhere inside your class declaration. The latter states for benchmarking all the instance methods,
+defined in the class. There are four wildcards available:
+
+* `:⋅`  — benchmark instance methods of a class;
+* `:⋅⋅` — benchmark instance methods of a class and all the superclasses;
+* `:×`  — benchmark class methods of a class;
+* `:××` — benchmark class methods of a class and all the superclasses;
+
+Let’s say there is a class `BmExample` that you want to benchmark:
+
+```ruby
+# Example module to test benchmarking functionality.
+module BmExamples
+  # Example class to test benchmarking functionality.
+  class BmExample
+    benchmark :do_it
+    ⌚ :do_other
+    
+    # The value
+    attr_reader :value
+    # Constructor.
+    # @param value [Fixnum] the value to add to 10 within {#value} initializer.
+    # @param addval [Fixnum] another value to add to 10 within {#value} initializer.
+    # @param attrs [Hash] additional parameters (ignored.)
+    def initialize value, addval, *attrs
+      @value = 10 + value + addval
+    end
+    # Multiplies {#value} by parameter given.
+    # @param deg [Fixnum]
+    # @return [Fixnum] {#value} multiplied by deg.
+    def do_it deg
+      @value * deg
+    end
+    # Produces a power of the parameter given.
+    # @param base [Fixnum]
+    # @return [Fixnum] {#value} in a power of base
+    def do_other base = 2
+      @value ** base
+    end
+  end
+end
+```
+
+The fifth and sixth lines of code will mark methods `do_it` and `do_other` for benchmarking.
+Actual benchmarking will take place during yard documentation production. This definitely will
+slow up the documentation generation, but in the production environment these do not
+interfere the normal execution timeline at all.
+
+After the generation is done, the methods are measured with an intellectual algorhytm:
+
+![YARD bench results](http://rocket-science.ru/img/yard-bench-result.png)
+
+The results are 〈almost〉 independent of the architecture of the target machine on which
+the measurements were done (they are normalized by `1_000_000.times {"foo bar baz".capitalize}`.)
+There are meaningful values for amounts of times to test chosen (three results, having
+significant figures in hundredth part.) The algorythm calculates the deviation of results and
+suggests `O(N)` power of function timing, whether possible.
 
 ## Installation
 
@@ -20,12 +95,16 @@ Or install it yourself as:
 
 Put the following code anywhere within your class:
 
-    benchmark :func1, :func2
+```ruby
+benchmark :func1, :func2
+```
     
 or even:
 
-    class String
-       ⌚ :⋅
+```ruby
+class String
+  ⌚ :⋅
+```
 
 and the benchmarks for the chosen functions will be included in yardoc.
 

data/lib/yard-bench/version.rb

@@ -2,6 +2,6 @@ require 'yard'
 
 module YARD
   module Bench
-    VERSION = "0.0.2"
+    VERSION = "0.0.3"
   end
 end

data/yard-bench.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.description = %Q{YARD plugin, which adds a benchmarking results to YARDoc}
   s.extra_rdoc_files = [
     'LICENSE',
-    'README.md',
+    'README.md'
   ]
 
   s.required_rubygems_version = Gem::Requirement.new('>= 1.3.7')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-bench
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Alexei Matyushkin