switch to YARD for documentation

Gemfile.lock

@@ -11,6 +11,7 @@ GEM
     rake (10.3.2)
     rdoc (4.1.1)
       json (~> 1.4)
+    redcarpet (3.1.2)
     rspec (3.0.0)
       rspec-core (~> 3.0.0)
       rspec-expectations (~> 3.0.0)
@@ -23,6 +24,7 @@ GEM
     rspec-mocks (3.0.2)
       rspec-support (~> 3.0.0)
     rspec-support (3.0.2)
+    yard (0.8.7.4)
 
 PLATFORMS
   ruby
@@ -30,5 +32,7 @@ PLATFORMS
 DEPENDENCIES
   rake
   rdoc
+  redcarpet
   rspec
+  yard
   yawpa!

README.md

@@ -10,41 +10,47 @@ Yet Another Way to Parse Arguments is an argument-parsing library for Ruby.
 
 ## Example 1
 
-    require 'yawpa'
+```ruby
+require "yawpa"
 
 options = {
   version: {},
-      verbose: {short: 'v'},
+  verbose: {short: "v"},
   get: {nargs: 1},
   set: {nargs: 2},
 }
 opts, args = Yawpa.parse(ARGV, options)
 opts.each_pair do |opt, val|
 end
+```
 
 ## Example 2
 
-    require 'yawpa'
+```ruby
+require "yawpa"
 
 options = {
   version: {},
-      help: {short: 'h'},
+  help: {short: "h"},
 }
 opts, args = Yawpa.parse(ARGV, options, posix_order: true)
 if opts[:version]
   puts "my app, version 1.2.3"
 end
-    if args[0] == 'subcommand'
+if args[0] == "subcommand"
   subcommand_options = {
-        'server': {nargs: (1..2), short: 's'},
-        'dst': {nargs: 1, short: 'd'},
+    "server": {nargs: (1..2), short: "s"},
+    "dst": {nargs: 1, short: "d"},
   }
   opts, args = Yawpa.parse(args, subcommand_options)
 end
+```
 
 ## Using Yawpa.parse()
 
+```ruby
 opts, args = Yawpa.parse(params, options, flags = {})
+```
 
 Parse input parameters looking for options according to rules given in flags
 
@@ -60,13 +66,15 @@ or insufficient arguments are present for an option.
 
 ### Example `options`
 
+```ruby
 {
   version: {},
-      verbose: {short: 'v'},
+  verbose: {short: "v"},
   server: {nargs: (1..2)},
   username: {nargs: 1},
   password: {nargs: 1},
 }
+```
 
 The keys of the `options` hash can be either strings or symbols.
 

Rakefile.rb

@@ -6,14 +6,13 @@ rescue Bundler::BundlerError => e
 end
 require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
-require "rdoc/task"
+require "yard"
 
 RSpec::Core::RakeTask.new('spec')
 
 task :default => :spec
 
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'Yet Another Way to Parse Arguments'
-  rdoc.rdoc_files.include('lib/**/*.rb')
+YARD::Rake::YardocTask.new do |yard|
+  yard.options = ["--title", "Yet Another Way to Parse Arguments"]
+  yard.files = ["lib/**/*.rb"]
 end

lib/yawpa.rb

@@ -7,32 +7,24 @@ require "yawpa/version"
 # it just provides a simple functional interface for parsing options,
 # supporting subcommands and arbitrary numbers of arguments for each option.
 #
-# == Features
-#
+# Features:
 # - POSIX or non-POSIX mode (supports subcommands using POSIX mode)
 # - Options can require an arbitrary number of parameters
-# - Options can be defined with a range specifying the allowed number of parameters
+# - Options can be defined with a range specifying the allowed number of
+#   parameters
 module Yawpa
-  # Exception class raised when an unknown option is observed
+  # Exception class raised when an unknown option is observed.
   class ArgumentParsingException < Exception; end
 
-  module_function
-  # :call-seq:
+  # Parse input parameters looking for options according to rules given in
+  # flags.
+  # Syntax:
   #   opts, args = parse(params, options, flags = {})
   #
-  # Parse input parameters looking for options according to rules given in flags
-  #
-  # - +params+ is the list of program parameters to parse.
-  # - +options+ is a hash containing the long option names as keys, and hashes
-  #   containing special flags for the options as values (example below).
-  # - +flags+ is optional. It supports the following keys:
-  #   - +:posix_order+: Stop processing parameters when a non-option is seen.
-  #     Set this to +true+ if you want to implement subcommands.
-  #
   # An ArgumentParsingException will be raised if an unknown option is observed
   # or insufficient arguments are present for an option.
   #
-  # == Example +options+
+  # Example +options+:
   #
   #   {
   #     version: {},
@@ -42,7 +34,7 @@ module Yawpa
   #     password: {nargs: 1},
   #   }
   #
-  # The keys of the +options+ hash can be either strings or symbols.
+  # The keys of the +options+ Hash can be either strings or symbols.
   #
   # Options that have no special flags should have an empty hash as the value.
   #
@@ -51,14 +43,28 @@ module Yawpa
   # - +:nargs+: specify an exact number or range of possible numbers of
   #   arguments to the option
   #
-  # == Return values
+  # @param params [Array]
+  #   List of program parameters to parse.
+  # @param options [Hash]
+  #   Hash containing the long option names as keys, and hashes containing
+  #   special flags for the options as values (example above).
+  # @param flags [Hash]
+  #   Optional flags dictating how {.parse} should do its job.
+  # @option flags [Boolean] :posix_order
+  #   Stop processing parameters when a non-option argument is seen.
+  #   Set this to +true+ if you want to implement subcommands.
   #
-  # The returned +opts+ value will be a hash with the observed options as
-  # keys and any option arguments as values.
-  # The returned +args+ will be an array of the unprocessed parameters (if
-  # +:posix_order+ was passed in +flags+, this array might contain further
-  # options that were not processed after observing a non-option parameters).
-  def parse(params, options, flags = {})
+  # @return [Array]
+  #   Two-element array containing +opts+ and +args+ return values.
+  #   +opts+::
+  #     The returned +opts+ value will be a Hash with the observed
+  #     options as keys and any option arguments as values.
+  #   +args+::
+  #     The returned +args+ will be an Array of the unprocessed
+  #     parameters (if +:posix_order+ was passed in +flags+, this array might
+  #     contain further options that were not processed after observing a
+  #     non-option parameters).
+  def self.parse(params, options, flags = {})
     options = _massage_options(options)
     opts = {}
     args = []
@@ -116,7 +122,7 @@ module Yawpa
   end
 
   # Internal helper method to gather arguments for an option
-  def _gather(nargs, start_idx, params, initial, param_key, result) # :nodoc:
+  def self._gather(nargs, start_idx, params, initial, param_key, result)
     n_gathered = 0
     if initial and initial != ''
       result << initial
@@ -137,9 +143,10 @@ module Yawpa
     end
     num_indices_used
   end
+  private_class_method :_gather
 
   # Internal helper method to format the options in a consistent format
-  def _massage_options(options) # :nodoc:
+  def self._massage_options(options)
     {}.tap do |newopts|
       options.each_pair do |k, v|
         newkey = k.to_s
@@ -151,12 +158,14 @@ module Yawpa
       end
     end
   end
+  private_class_method :_massage_options
 
   # Internal helper method to find an option configuration by short name
-  def _find_opt_config_by_short_name(options, short_name) # :nodoc:
+  def self._find_opt_config_by_short_name(options, short_name)
     options.each_pair do |k, v|
       return v if v[:short] == short_name
     end
     nil
   end
+  private_class_method :_find_opt_config_by_short_name
 end

yawpa.gemspec

@@ -18,4 +18,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rspec"
   gem.add_development_dependency "rake"
   gem.add_development_dependency "rdoc"
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "redcarpet"
 end