rprogram 0.1.6 → 0.1.7

data/History.txt

@@ -1,3 +1,12 @@
+=== 0.1.7 / 2009-09-21
+
+* Require Hoe >= 2.3.3.
+* Require YARD >= 0.2.3.5.
+* Require RSpec >= 1.2.8.
+* Use 'hoe/signing' for signed RubyGems.
+* Moved to YARD based documentation.
+* All specs pass on JRuby 1.3.1.
+
 === 0.1.6 / 2009-06-30
 
 * Use Hoe 2.2.0.

data/Manifest.txt

@@ -19,6 +19,12 @@ lib/rprogram/nameable.rb
 lib/rprogram/program.rb
 lib/rprogram/rprogram.rb
 lib/rprogram/version.rb
+lib/rprogram/yard.rb
+lib/rprogram/yard/handlers.rb
+lib/rprogram/yard/handlers/ruby.rb
+lib/rprogram/yard/handlers/ruby/metaclass_eval_handler.rb
+lib/rprogram/yard/handlers/ruby/legacy.rb
+lib/rprogram/yard/handlers/ruby/legacy/metaclass_eval_handler.rb
 spec/spec_helper.rb
 spec/classes/named_program.rb
 spec/classes/aliased_program.rb

data/README.txt

@@ -19,6 +19,10 @@ system.
 * Supports leading/tailing non-options.
 * Supports long-options and short-options.
 * Supports custom formating of options.
+
+== REQUIREMENTS:
+
+* {YARD}[http://yard.soen.ca/] >= 0.2.3.5
   
 == INSTALL:
 

data/Rakefile

@@ -4,11 +4,22 @@ require 'rubygems'
 require 'hoe'
 require 'hoe/signing'
 require './tasks/spec.rb'
+require './tasks/yard.rb'
 
 Hoe.spec('rprogram') do
   self.rubyforge_name = 'rprogram'
   self.developer('Postmodern', 'postmodern.mod3@gmail.com')
   self.remote_rdoc_dir = ''
+
+  self.extra_deps = [
+    ['yard', '>=0.2.3.5']
+  ]
+
+  self.extra_dev_deps = [
+    ['rspec', '>=1.2.8']
+  ]
+
+  self.spec_extras = {:has_rdoc => 'yard'}
 end
 
 # vim: syntax=Ruby

data/lib/rprogram/compat.rb

@@ -1,8 +1,11 @@
 module RProgram
   module Compat
     #
-    # Returns the native _platform_.
+    # Determines the native platform.
     #
+    # @return [String] The native platform.
+    #
+    # @example
     #   Compat.arch  #=> "linux"
     #
     def Compat.platform
@@ -10,10 +13,11 @@ module RProgram
     end
 
     #
-    # Returns an array representing the +PATH+ environment variable.
-    # If the +PATH+ environment variable is not setup, an empty array will
-    # be returned.
+    # Determines the contents of the +PATH+ environment variable.
+    #
+    # @return [Array] The contents of the +PATH+ environment variable.
     #
+    # @example
     #   Compat.paths #=> ["/bin", "/usr/bin"]
     #
     def Compat.paths
@@ -29,9 +33,13 @@ module RProgram
     end
 
     #
-    # Finds the program matching _name_ and returns it's full path.
-    # If the program was not found, +nil+ will be returned.
+    # Finds the full-path of the program with the matching name.
+    #
+    # @param [String] name The name of the program to find.
     #
+    # @return [String, nil] The full-path of the desired program.
+    #
+    # @example
     #   Compat.find_program('as')  #=> "/usr/bin/as"
     #
     def Compat.find_program(name)
@@ -45,10 +53,14 @@ module RProgram
     end
 
     #
-    # Finds the program matching one of the names within _names_ and
-    # returns it's full path. If no program was found matching any of
-    # the names, the +nil+ will be returned.
+    # Finds the program matching one of the matching names.
+    #
+    # @param [Array] names The names of the program to use while
+    #                      searching for the program.
+    #
+    # @return [String, nil] The first full-path for the program.
     #
+    # @example
     #   Compat.find_program_by_names("gas","as")  #=> "/usr/bin/as"
     #
     def Compat.find_program_by_names(*names)

data/lib/rprogram/nameable.rb

@@ -3,33 +3,37 @@ require 'rprogram/compat'
 
 module RProgram
   module Nameable
-    def self.included(base) # :nodoc:
+    def self.included(base)
       base.metaclass_eval do
         #
-        # Returns the name of the program.
+        # @return [String] The name of the program.
         #
         def program_name
           @program_name ||= nil
         end
 
         #
-        # Returns an Array of the program's aliases.
+        # @return [Array] The program's aliases.
         #
         def program_aliases
           @program_aliases ||= []
         end
 
         #
-        # Returns an Array of all names the program is known by, combining
-        # both program_name and program_aliases.
+        # Combines program_name with program_aliases.
+        #
+        # @return [Array] Names the program is known by.
         #
         def program_names
           ([program_name] + program_aliases).compact
         end
 
         #
-        # Sets the program name for a class to the specified _name_.
+        # Sets the program name for the class.
+        #
+        # @param [String, Symbol] name The new program name.
         #
+        # @example
         #   name_program 'ls'
         #
         def name_program(name)
@@ -37,8 +41,11 @@ module RProgram
         end
 
         #
-        # Sets the program aliases for a class to the specified _aliases_.
+        # Sets the program aliases for the class.
+        #
+        # @param [Array] aliases The new program aliases.
         #
+        # @example
         #   alias_program 'vim', 'vi'
         #
         def alias_program(*aliases)
@@ -48,21 +55,21 @@ module RProgram
     end
 
     #
-    # Returns the program name of a class.
+    # @return [String] The program name of the class.
     #
     def program_name
       self.class.program_name
     end
 
     #
-    # Returns the program aliases.
+    # @return [Array] The program aliases of the class.
     #
     def program_aliases
       self.class.program_aliases
     end
 
     #
-    # Returns the program names.
+    # @return [Array] The program names of the class.
     #
     def program_names
       self.class.program_names

data/lib/rprogram/non_option.rb

@@ -8,16 +8,19 @@ module RProgram
     attr_reader :multiple
 
     #
-    # Creates a new NonOption object with the specified _options_.
+    # Creates a new NonOption object.
     #
-    # _options_ may contain the following keys:
-    # <tt>:name</tt>:: The name of the non-option.
-    # <tt>:leading</tt>:: Implies the non-option is a leading non-option.
-    #                     Defaults to +false+, if not given.
-    # <tt>:tailing</tt>:: Implies the non-option is a tailing non-option.
-    #                     Defaults to +true+, if not given.
-    # <tt>:multiple</tt>:: Implies the non-option maybe given an Array
-    #                      of values. Defaults to +false+, if not given.
+    # @param [Hash] options Additional options.
+    # @option options [Symbol] :name The name of the non-option.
+    # @option options [true, false] :leading (true)
+    #                                        Implies the non-option is a
+    #                                        leading non-option.
+    # @option options [false, true] :tailing (false)
+    #                                        Implies the non-option is a
+    #                                        tailing non-option.
+    # @option options [false, true] :multiple (false)
+    #                                         Implies the non-option maybe
+    #                                         given an Array of values.
     #
     def initialize(options={})
       @name = options[:name]
@@ -34,24 +37,32 @@ module RProgram
     end
 
     #
-    # Returns +true+ if the non-options arguments are tailing, returns
-    # +false+ otherwise.
+    # Determines whether the non-option's arguments are tailing.
+    #
+    # @return [true, false] Specifies whether the non-option's arguments are
+    #                       tailing.
     #
     def tailing?
       @tailing == true
     end
 
     #
-    # Returns +true+ if the non-options arguments are leading, returns
-    # +false+ otherwise.
+    # Determines whether the non-option's arguments are leading.
+    #
+    # @return [true, false] Specifies whether the non-option's arguments are
+    #                       leading.
     #
     def leading?
       !(@tailing)
     end
 
     #
-    # Returns an +Array+ of the arguments for the non-option with the
-    # specified _value_.
+    # Formats the arguments for the non-option.
+    #
+    # @param [Hash, Array, String, nil] value The value to use for the
+    #                                         arguments of the non-option.
+    #                                   
+    # @return [Array] The arguments for the non-option.
     #
     def arguments(value)
       return [] unless value

data/lib/rprogram/option.rb

@@ -17,26 +17,35 @@ module RProgram
     attr_reader :sub_options
 
     #
-    # Creates a new Option object with the specified _options_. If a _block_
+    # Creates a new Option object with. If a _block_
     # is given it will be used for the custom formating of the option. If a
     # _block_ is not given, the option will use the default_format when
     # generating the arguments.
     #
-    # _options_ must contain the following key:
-    # <tt>:flag</tt>:: The command-line flag to use.
+    # @param [Hash] options Additional options.
+    # @option options [String] :flag The command-line flag to use.
+    # @option options [true, false] :equals (false)
+    #                                       Implies the option maybe
+    #                                       formated as
+    #                                       <tt>"--flag=value"</tt>.
     #
-    # _options_ may also contain the following keys:
-    # <tt>:equals</tt>:: Implies the option maybe formated as
-    #                    <tt>"--flag=value"</tt>. Defaults to +falue+, if
-    #                    not given.
-    # <tt>:multuple</tt>:: Specifies the option maybe given an Array of
-    #                      values. Defaults to +false+, if not given.
-    # <tt>:separator</tt>:: The separator to use for formating multiple
-    #                       arguments into one +String+. Cannot be used
-    #                       with <tt>:multiple</tt>.
-    # <tt>:sub_options</tt>:: Specifies that the option contains
-    #                         sub-options. Defaults to false, if not given.
+    # @option options [true, false] :multiple (false)
+    #                                         Specifies the option maybe
+    #                                         given an Array of values.
+    # @option options [String] :separator The separator to use for
+    #                                     formating multiple arguments into
+    #                                     one +String+. Cannot be used with
+    #                                     the +:multiple+ option.
+    # @option options [true, false] :sub_options (false)
+    #                                            Specifies that the option
+    #                                            contains sub-options.
     #
+    # @yield [option, value] If a block is given, it will be used to format
+    #                        each value of the option.
+    # @yieldparam [Option] option The option that is being formatted.
+    # @yieldparam [String, Array] value The value to format for the
+    #                                   option. May be an Array, if multiple
+    #                                   values are allowed with the option.
     #
     def initialize(options={},&block)
       @flag = options[:flag]
@@ -64,8 +73,11 @@ module RProgram
     end
 
     #
-    # Returns an +Array+ of the arguments for the option with the specified
-    # _value_.
+    # Formats the arguments for the option.
+    #
+    # @param [Hash, Array, String] value The arguments to format.
+    #
+    # @return [Array] The formatted arguments of the option.
     #
     def arguments(value)
       return [@flag] if value == true

data/lib/rprogram/option_list.rb

@@ -2,7 +2,9 @@ module RProgram
   class OptionList < Hash
 
     #
-    # Creates a new OptionList object with the given _options_.
+    # Creates a new OptionList object.
+    #
+    # @param [Hash{Symbol => String}] options The options to start with.
     #
     def initialize(options={})
       super(options)
@@ -13,6 +15,7 @@ module RProgram
     #
     # Provides transparent access to the options within the option list.
     #
+    # @example
     #   opt_list = OptionList.new(:name => 'test')
     #   opt_list.name
     #   # => "test"

data/lib/rprogram/options.rb

@@ -4,18 +4,23 @@ require 'rprogram/option'
 
 module RProgram
   module Options
-    def self.included(base) # :nodoc:
+    def self.included(base)
       base.metaclass_eval do
         #
-        # Returns a Hash of all defined non-options.
+        # @return [Hash] All defined non-options of the class.
         #
         def non_options
           @non_options ||= {}
         end
 
         #
-        # Returns +true+ if the non-option with the specified _name_ was
-        # defined, returns +false+ otherwise.
+        # Searches for the non-option with the matching name in the class
+        # and it's ancestors.
+        #
+        # @param [Symbol, String] name The name to search for.
+        #
+        # @return [true, false] Specifies whether the non-option with the
+        #                       matching name was defined.
         #
         def has_non_option?(name)
           name = name.to_sym
@@ -30,7 +35,12 @@ module RProgram
         end
 
         #
-        # Returns the non-option known by _name_, returns +nil+ otherwise.
+        # Searches for the non-option with the matching name in the class
+        # and it's ancestors.
+        #
+        # @param [Symbol, String] name The name to search for.
+        #
+        # @return [NonOption] The non-option with the matching name.
         #
         def get_non_option(name)
           name = name.to_sym
@@ -47,15 +57,20 @@ module RProgram
         end
 
         #
-        # Returns a Hash of all defined options.
+        # @return [Hash] All defined options for the class.
         #
         def options
           @options ||= {}
         end
 
         #
-        # Returns +true+ if an option with the specified _name_ was defined,
-        # returns +false+ otherwise.
+        # Searches for the option with the matching name in the class and
+        # it's ancestors.
+        #
+        # @param [Symbol, String] name The name to search for.
+        #
+        # @return [true, false] Specifies whether the option with the
+        #                       matching name was defined.
         #
         def has_option?(name)
           name = name.to_sym
@@ -70,8 +85,12 @@ module RProgram
         end
 
         #
-        # Returns the option with the specified _name_, returns +nil+
-        # otherwise.
+        # Searches for the option with the matching name in the class and
+        # it's ancestors.
+        #
+        # @param [Symbol, String] name The name to search for.
+        #
+        # @return [Option] The option with the matching name.
         #
         def get_option(name)
           name = name.to_sym
@@ -88,31 +107,28 @@ module RProgram
     end
 
     #
-    # Returns +true+ if the non-option with the specified _name_ was
-    # defined, returns +false+ otherwise.
+    # @see self.has_non_option?
     #
     def has_non_option?(name)
       self.class.has_non_option?(name)
     end
 
     #
-    # Returns the non-option known by _name_, returns +nil+ otherwise.
+    # @see self.get_non_option
     #
     def get_non_option(name)
       self.class.get_non_option(name)
     end
 
     #
-    # Returns +true+ if an option with the specified _name_ was defined,
-    # returns +false+ otherwise.
+    # @see self.has_option?
     #
     def has_option?(name)
       self.class.has_option?(name)
     end
 
     #
-    # Returns the option with the specified _name_, returns +nil+
-    # otherwise.
+    # @see self.get_option
     #
     def get_option(name)
       self.class.get_option(name)

data/lib/rprogram/program.rb

@@ -16,10 +16,18 @@ module RProgram
     attr_reader :name
 
     #
-    # Creates a new Program object from _path_. If _path_ is not a valid
-    # file, a ProgramNotFound exception will be thrown. If a _block_ is
-    # given, it will be passed the newly created Program.
+    # Creates a new Program object.
     #
+    # @param [String] path The full-path of the program.
+    #
+    # @yield [prog] If a block is given, it will be passed the newly
+    #               created Program object.
+    # @yieldparam [Program] prog The newly created program object.
+    #
+    # @raise [ProgramNotFound] Specifies the given path was not a valid
+    #                          file.
+    #
+    # @example
     #   Program.new('/usr/bin/ls')
     #
     def initialize(path,&block)
@@ -36,13 +44,27 @@ module RProgram
     end
 
     #
-    # Creates a new program object with the specified _path_, if _path_
-    # is a valid file. Any given _arguments_ or a given _block_ will be used
-    # in creating the new program.
+    # Creates a new program object.
+    #
+    # @param [String] path The full-path of the program.
+    # @param [Array] arguments Additional arguments to initialize the
+    #                          program with.
+    #
+    # @yield [prog] If a block is given, it will be passed the newly
+    #               created Program object.
+    # @yieldparam [Program] prog The newly created program object.
     #
-    #   Program.find_with_path('/bin/cd') # => Program
+    # @return [Program, nil] Returns the newly created Program object.
+    #                        If the given path was not a valid file,
+    #                        +nil+ will be returned.
     #
-    #   Program.find_with_path('/obviously/fake') # => nil
+    # @example
+    #   Program.find_with_path('/bin/cd')
+    #   # => Program
+    #
+    # @example
+    #   Program.find_with_path('/obviously/fake')
+    #   # => nil
     #
     def self.find_with_path(path,*arguments,&block)
       return self.new(path,*arguments,&block) if File.file?(path)
@@ -53,9 +75,25 @@ module RProgram
     # if a path within _paths_ is a valid file. Any given _arguments_ or
     # a given _block_ will be used in creating the new program.
     #
-    #   Program.find_with_paths(['/bin/cd','/usr/bin/cd']) # => Program
+    # @param [Array] paths The Array of paths to search for the program.
+    # @param [Array] arguments Additional arguments to initialize
+    #                          the program with.
+    #
+    # @yield [prog] If a block is given, it will be passed the newly
+    #               created Program object.
+    # @yieldparam [Program] prog The newly created program object.
+    #
+    # @return [Program, nil] Returns the newly created Program object.
+    #                        If none of the given paths were valid files,
+    #                        +nil+ will be returned.
     #
-    #   Program.find_with_paths(['/obviously/fake','/bla']) # => nil
+    # @example
+    #   Program.find_with_paths(['/bin/cd','/usr/bin/cd'])
+    #   # => Program
+    #
+    # @example
+    #   Program.find_with_paths(['/obviously/fake','/bla'])
+    #   # => nil
     #
     def self.find_with_paths(paths,*arguments,&block)
       paths.each do |path|
@@ -64,15 +102,27 @@ module RProgram
     end
 
     #
-    # Finds and creates the program using it's +program_names+ and returns
-    # a new Program object. If the program cannot be found by any of it's
-    # +program_names+, a ProramNotFound exception will be raised. Any given
-    # _arguments_ or a given _block_ will be used in creating the new program.
+    # Finds and creates the program using it's +program_names+.
+    #
+    # @param [Array] arguments Additional arguments to initialize the
+    #                          program object with.
     #
-    #   Program.find # => Program
+    # @yield [prog] If a block is given, it will be passed the newly
+    #               created Program object.
+    # @yieldparam [Program] prog The newly created program object.
     #
+    # @return [Program] The newly created program object.
+    #
+    # @raise [ProgramNotFound] Non of the +program_names+ represented
+    #                          valid programs on the system.
+    #
+    # @example
+    #   Program.find
+    #   # => Program
+    #
+    # @example
     #   MyProgram.find('stuff','here') do |prog|
-    #     ...
+    #     # ...
     #   end
     #
     def self.find(*arguments,&block)
@@ -88,15 +138,20 @@ module RProgram
     end
 
     #
-    # Runs the program with the specified _arguments_ and returns
-    # either +true+ or +false+, depending on the exit status of the
-    # program.
+    # Runs the program.
+    #
+    # @param [Array] args Addition arguments to run the program with.
+    #
+    # @return [true, false] Specifies the exit status of the program.
     #
+    # @example
     #   echo = Program.find_by_name('echo')
     #   echo.run('hello')
     #   # hello
     #   # => true
     #
+    # @see Kernel.system
+    #
     def run(*args)
       args = args.map { |arg| arg.to_s }
 
@@ -108,15 +163,25 @@ module RProgram
     end
 
     #
-    # Runs the program with the specified _task_ object.
+    # Runs the program with the arguments from the given task.
+    #
+    # @param [Task] task The task who's arguments will be used to run the
+    #                    program.
+    #
+    # @return [true, false] Specifies the exit status of the program.
+    #
+    # @see Kernel.system
     #
     def run_task(task)
       run(*(task.arguments))
     end
 
     #
-    # Returns the path of the program.
+    # Converts the program to a String.
+    #
+    # @return [String] The path of the program.
     #
+    # @example
     #   Program.find_by_name('echo').to_s
     #   # => "/usr/bin/echo"
     #

data/lib/rprogram/rprogram.rb

@@ -1,15 +1,17 @@
 module RProgram
   #
-  # Returns +true+ if RProgram debugging messages are enabled, returns
-  # +false+ if they are not enabled.
+  # @return [true, false] Specifies whether debugging messages are enabled
+  #                       for RProgram. Defaults to false, if not set.
   #
   def RProgram.debug
     @@rprogram_debug ||= false
   end
 
   #
-  # Enables or disables RProgram debugging messages depending on the
-  # specified _value_.
+  # Enables or disables debugging messages for RProgram.
+  #
+  # @param [true, false] value The new value of RProgram.debug.
+  # @return [true, false] The new value of RProgram.debug.
   #
   def RProgram.debug=(value)
     @@rprogram_debug = value

data/lib/rprogram/task.rb

@@ -7,13 +7,20 @@ module RProgram
     include Options
 
     #
-    # Creates a new Task object with the given _options_. If a block is
-    # given, it is passed the newly created Task object.
+    # Creates a new Task object.
     #
+    # @param [Hash{Symbol => Object}] options Additional task options.
+    #
+    # @yield [task] If a block is given, it will be passed the newly
+    #               created task.
+    # @yieldparam [Task] task The newly created Task object.
+    #
+    # @example
     #   Task.new(:test => 'example', :count => 2, :verbose => true)
     #
+    # @example
     #   Task.new(:help => true) do |task|
-    #     ...
+    #     # ...
     #   end
     #
     def initialize(options={},&block)
@@ -24,23 +31,37 @@ module RProgram
     end
 
     #
-    # Returns the compiled _arguments_ from a Task object created
-    # with the given _options_ and _block_.
+    # Creates a new Task object, then formats command-line arguments
+    # using the Task object.
+    #
+    # @param [Hash{Symbol => Object}] options Additional task options.
+    #
+    # @yield [task] If a block is given, it will be passed the newly
+    #               created task.
+    # @yieldparam [Task] task The newly created Task object.
     #
+    # @return [Array] The formatted arguments from a Task object.
+    #
+    # @example
     #   MyTask.arguments(:verbose => true, :count => 2)
+    #   # => [...]
     #
+    # @example
     #   MyTask.arguments do |task|
     #     task.verbose = true
     #     task.file = 'output.txt'
     #   end
+    #   # => [...]
     #
     def self.arguments(options={},&block)
       self.new(options,&block).arguments
     end
 
     #
-    # Returns an array of _arguments_ generated from all the leading
-    # non-options of the task and it's sub-tasks.
+    # Generates the command-line arguments for all leading non-options.
+    #
+    # @return [Array] The command-line arguments generated from all the
+    #                 leading non-options of the task and it's sub-tasks.
     #
     def leading_non_options
       args = []
@@ -63,8 +84,10 @@ module RProgram
     end
 
     #
-    # Returns an array of _arguments_ generated from all the options
-    # of the task and it's sub-tasks.
+    # Generates the command-line arguments from all options.
+    #
+    # @return [Array] The command-line arguments generated from all the
+    #                 options of the task and it's sub-tasks.
     #
     def options
       args = []
@@ -84,8 +107,10 @@ module RProgram
     end
 
     #
-    # Returns an array of _arguments_ generated from all the tailing
-    # non-options of the task and it's sub-tasks.
+    # Generates the command-line arguments from all tailing non-options.
+    #
+    # @return [Array] The command-line arguments generated from all the
+    #                 tailing non-options of the task and it's sub-tasks.
     #
     def tailing_non_options
       args = []
@@ -108,8 +133,11 @@ module RProgram
     end
 
     #
-    # Returns an array of _arguments_ compiled from the _arguments_ of
-    # the tasks leading non_options, options and tailing non-options.
+    # Generates the command-line arguments from the task.
+    #
+    # @return [Array] The command-line arguments compiled from the
+    #                 leading non-options, options and tailing non-options
+    #                 of the task and it's sub-tasks.
     #
     def arguments
       leading_non_options + options + tailing_non_options
@@ -118,8 +146,12 @@ module RProgram
     protected
 
     #
-    # Defines a sub-task of _name_ and class of _task_.
+    # Defines a sub-task.
+    #
+    # @param [String, Symbol] name The name of the sub-task.
+    # @param [Task] task The task class of the sub-task.
     #
+    # @example
     #   subtask :extra, ExtraTask
     #
     def self.subtask(name,task)
@@ -141,10 +173,24 @@ module RProgram
     end
 
     #
-    # Defines a non-option with the given _options_.
+    # Defines a non-option.
     #
+    # @param [Hash] options Additional options for the non-option.
+    # @option options [Symbol] :name The name of the non-option.
+    # @option options [true, false] :leading (true)
+    #                                        Implies the non-option is a
+    #                                        leading non-option.
+    # @option options [false, true] :tailing (false)
+    #                                        Implies the non-option is a
+    #                                        tailing non-option.
+    # @option options [false, true] :multiple (false)
+    #                                         Implies the non-option maybe
+    #                                         given an Array of values.
+    #
+    # @example
     #   non_option :name => 'input_file', :tailing => true
     #
+    # @example
     #   non_option :name => 'file', :tailing => true, :multiple => true
     #
     def self.non_option(options={})
@@ -166,22 +212,26 @@ module RProgram
     end
 
     #
-    # Defines a long-option with the specified _options_.
-    #
-    # _options_ must contain the following keys:
-    # <tt>:flag</tt>:: The flag to use for the option.
+    # Defines a long-option.
     #
-    # _options_ may also contain the following keys:
-    # <tt>:name</tt>:: The name of the option. Defaults to the
-    #                  flag_namify'ed form of <tt>options[:flag]</tt>,
-    #                  if not given.
-    # <tt>:multiply</tt>:: Specifies that the option may appear multiple
-    #                      times in the arguments.
-    # <tt>:sub_options</tt>:: Specifies that the option contains multiple
-    #                  sub-options.
+    # @param [Hash] options Additional options of the long-option.
+    # @option options [String] :flag The flag to use for the option.
+    # @option options [Symbol] :name The name of the option. Defaults to
+    #                                the flag_namify'ed form of
+    #                                <tt>options[:flag]</tt>, if not given.
+    # @option options [true, false] :multiply (false)
+    #                                         Specifies that the option may
+    #                                         appear multiple times in the
+    #                                         arguments.
+    # @option options [true, false] :sub_options (false)
+    #                                            Specifies that the option
+    #                                            contains multiple
+    #                                            sub-options.
     #
+    # @example
     #   long_option :flag => '--output'
     #
+    # @example
     #   long_option :flag => '-f', :name => :file
     #
     def self.long_option(options={},&block)
@@ -193,18 +243,21 @@ module RProgram
     end
 
     #
-    # Defines a short_option with the specified _options_.
+    # Defines a short_option.
     #
-    # _options_ must contain the following keys:
-    # <tt>:name</tt>:: The name of the option.
-    # <tt>:flag</tt>:: The flag to use for the option.
-    #
-    # _options_ may also contain the following keys:
-    # <tt>:multiply</tt>:: Specifies that the option may appear multiple
-    #                      times in the arguments.
-    # <tt>:sub_options</tt>:: Specifies that the option contains multiple
-    #                  sub-options.
+    # @param [Hash] options Additional options for the short-option.
+    # @option options [Symbol, String] :name The name of the short-option.
+    # @option options [String] :flag The flag to use for the short-option.
+    # @option options [true, false] :multiply (false)
+    #                                         Specifies that the option may
+    #                                         appear multiple times in the
+    #                                         arguments.
+    # @option options [true, false] :sub_options (false)
+    #                                            Specifies that the option
+    #                                            contains multiple
+    #                                            sub-options.
     #
+    # @example
     #   short_option :flag => '-c', :name => :count
     #
     def self.short_option(options,&block)
@@ -212,17 +265,19 @@ module RProgram
     end
 
     #
-    # Defines an option with the specified _options_ and the given _block_.
-    #
-    # _options_ must contain the following keys:
-    # <tt>:name</tt>:: The name of the option.
-    # <tt>:flag</tt>:: The flag to use for the option.
+    # Defines an option.
     #
-    # _options_ may also contain the following keys:
-    # <tt>:multiply</tt>:: Specifies that the option may appear multiple
-    #                      times in the arguments.
-    # <tt>:sub_options</tt>:: Specifies that the option contains multiple
-    #                  sub-options.
+    # @param [Hash] options Additional options.
+    # @option options [Symbol, String] :name The name of the option.
+    # @option options [String] :flag The flag to use for the option.
+    # @option options [true, false] :multiple (false)
+    #                                         Specifies that the option may
+    #                                         appear multiple times in the
+    #                                         arguments.
+    # @option options [true, false] :sub_options (false)
+    #                                            Specifies that the option
+    #                                            contains multiple
+    #                                            sub-options.
     #
     def self.define_option(options,&block)
       method_name = options[:name].to_sym
@@ -250,8 +305,14 @@ module RProgram
 
     #
     # Converts a long-option flag to a Ruby method name.
+    #
+    # @param [String] flag The command-line flag to convert.
+    #
+    # @return [String] A method-name compatible version of the given flag.
     # 
-    #   Task.flag_namify('--output-file')  # => "output_file"
+    # @example
+    #   Task.flag_namify('--output-file')
+    #   # => "output_file"
     #
     def Task.flag_namify(flag)
       flag = flag.to_s.downcase

data/lib/rprogram/version.rb

@@ -1,3 +1,4 @@
 module RProgram
-  VERSION = '0.1.6'
+  # Version of RProgram
+  VERSION = '0.1.7'
 end

data/lib/rprogram/yard/handlers/ruby/legacy/metaclass_eval_handler.rb

@@ -0,0 +1,21 @@
+require 'yard/handlers/ruby/legacy/base'
+
+module YARD
+  module Handlers
+    module Ruby
+      module Legacy
+        class MetaclassEvalHandler < Base
+
+          handles /(\A|\.)metaclass_eval(\s+|\()/
+
+          def process
+            if statement.block
+              parse_block(:namespace => namespace, :scope => :class)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/rprogram/yard/handlers/ruby/legacy.rb

@@ -0,0 +1 @@
+require 'rprogram/yard/handlers/ruby/legacy/metaclass_eval_handler'

data/lib/rprogram/yard/handlers/ruby/metaclass_eval_handler.rb

@@ -0,0 +1,18 @@
+require 'yard'
+
+module YARD
+  module Handlers
+    module Ruby
+      class MetaclassEvalHandler < YARD::Handlers::Ruby::Base
+
+        handles method_call(:metaclass_eval)
+
+        def process
+          if (block = statement.jump(:brace_block, :do_block).last)
+            parse_block(block, :namespace => namespace, :scope => :class)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rprogram/yard/handlers/ruby.rb

@@ -0,0 +1,2 @@
+require 'rprogram/yard/handlers/ruby/metaclass_eval_handler'
+require 'rprogram/yard/handlers/ruby/legacy'

data/lib/rprogram/yard/handlers.rb

@@ -0,0 +1 @@
+require 'rprogram/yard/handlers/ruby'

data/lib/rprogram/yard.rb

@@ -0,0 +1 @@
+require 'rprogram/yard/handlers'

data/spec/spec_helper.rb

@@ -1,5 +1,5 @@
 require 'rubygems'
-gem 'rspec', '>=1.1.3'
+gem 'rspec', '>=1.2.8'
 require 'spec'
 
 require 'rprogram/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rprogram
 version: !ruby/object:Gem::Version 
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors: 
 - Postmodern
@@ -30,9 +30,29 @@ cert_chain:
   pDj+ws7QjtH/Qcrr1l9jfN0ehDs=
   -----END CERTIFICATE-----
 
-date: 2009-06-30 00:00:00 -07:00
+date: 2009-09-25 00:00:00 -07:00
 default_executable: 
 dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.2.3.5
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.8
+    version: 
 - !ruby/object:Gem::Dependency 
   name: hoe
   type: :development
@@ -41,7 +61,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.2.0
+        version: 2.3.3
     version: 
 description: |-
   RProgram is a library for creating wrappers around command-line programs.
@@ -81,6 +101,12 @@ files:
 - lib/rprogram/program.rb
 - lib/rprogram/rprogram.rb
 - lib/rprogram/version.rb
+- lib/rprogram/yard.rb
+- lib/rprogram/yard/handlers.rb
+- lib/rprogram/yard/handlers/ruby.rb
+- lib/rprogram/yard/handlers/ruby/metaclass_eval_handler.rb
+- lib/rprogram/yard/handlers/ruby/legacy.rb
+- lib/rprogram/yard/handlers/ruby/legacy/metaclass_eval_handler.rb
 - spec/spec_helper.rb
 - spec/classes/named_program.rb
 - spec/classes/aliased_program.rb
@@ -96,7 +122,7 @@ files:
 - spec/nameable_spec.rb
 - spec/program_spec.rb
 - spec/task_spec.rb
-has_rdoc: true
+has_rdoc: yard
 homepage: http://rprogram.rubyforge.org/
 licenses: []
 
@@ -121,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rprogram
-rubygems_version: 1.3.4
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: RProgram is a library for creating wrappers around command-line programs