numru-misc 0.1.1 → 0.1.2

data/.ChangeLog.until201414

@@ -0,0 +1,44 @@
+Fri Mar 14  2014   T Koshiro < M Nakano [dennou-ruby:003646]
+	* install.rb: for Ruby 2.x
+
+Mon Aug 11  2011   T Horinouchi
+	* numru-misc-0.1.1 released (relase tag: numru-misc-0_1_1)
+	* LICENCE.txt: Added (BSD 2-clause licence)
+
+Mon Mar 15  2010   T Horinouchi
+	* numru-misc-0.1.0 released (relase tag: numru-misc-0_1_0)
+
+2008-02-05  S Otsuka
+	* install.rb: for ruby 1.9
+
+Fri May 13  2005   T Horinouchi
+	* numru-misc-0.0.6 released (relase tag: numru-misc-0_0_6)
+	* keywordopt.rb: KeywordOpt#keys --> public (returns @keys.dup).
+	  Added KeywordOpt#select_keys.
+Tue Aug 12  2004   T Horinouchi
+	* keywordopt.rb: modified KeywordOptAutoHelp#set to show help
+	  message if 'help'==true.
+Tue Aug 10  2004   T Horinouchi
+	* numru-misc-0.0.5 released (relase tag: numru-misc-0_0_5)
+	* package renamed from misc to numru-misc: started new CVS
+Fri Mar 19  2004   T Horinouchi
+	* emath.rb: basically, a refactoring
+	* install.rb: debug
+Wed Dec 10  2003   T Horinouchi
+	* misc-0.0.4 released
+	* emath.rb: NumRu::EMath --> NumRu::Misc::EMath
+	            Documentation.
+	* misc.rb: documentation update for EMath.
+Tue Oct  7  2003   T Horinouchi
+	* emath.rb: created
+Mon Sep  1  2003   T Horinouchi
+	* misc-0.0.3 released
+	* keywordopt.rb: minor debug of the help messaging in 
+	  KeywordOptAutoHelp#interpret
+Tue Aug 26  2003   T Horinouchi
+	* keywordopt.rb: added class KeywordOptAutoHelp. refined help.
+	  allowed KeywordOpt.new to accept another KeywordOpt.
+Mon Aug 25  2003   T Horinouchi
+	* keywordopt.rb: KeywordOpt#interpret slightly modified
+Mon Aug 25  2003   T Horinouchi
+	* version 0.0.2 released

data/.gitignore

@@ -0,0 +1,6 @@
+*.[oa]
+*~
+*.so
+Makefile
+ChangeLog
+/pkg/

data/ChangeLog

@@ -1,41 +1,93 @@
+2015-03-18  Takeshi Horinouchi  (HEAD, numru-misc-0_1_2, origin/master, origin/HEAD, master)
+Years updated.
+
+M	LICENSE.txt
+
+2015-03-18  Takeshi Horinouchi 
+To release version 0.1.2 (git tag numru-misc-0_1_2)
+
+M	lib/numru/misc/version.rb
+
+2015-03-18  Takeshi Horinouchi 
+To require 'numru/misc/version'
+
+M	lib/numru/misc.rb
+
+2015-03-18  Takeshi Horinouchi 
+Created lib/numru/misc/version.rb
+
+A	lib/numru/misc/version.rb
+
+2015-03-18  Takeshi Horinouchi 
+Renamed the current ChangeLog to back up.
+
+A	.ChangeLog.until201414
+D	ChangeLog
+
+2015-03-18  Takeshi Horinouchi 
+Registered files (patterns) to ignore in the repository
+
+A	.gitignore
+
+2014-03-13  koshiro 
+Fri Mar 14  2014   T Koshiro < M Nakano [dennou-ruby:003646]
+        * install.rb: for Ruby 2.x
+
+M	ChangeLog
+M	install.rb
+
+2011-08-11  T Horinouchi  (numru-misc-0_1_1)
 Mon Aug 11  2011   T Horinouchi
 	* numru-misc-0.1.1 released (relase tag: numru-misc-0_1_1)
 	* LICENCE.txt: Added (BSD 2-clause licence)
 
+M	ChangeLog
+A	LICENSE.txt
+
+2010-03-15  T Horinouchi  (numru-misc-0_1_0)
 Mon Mar 15  2010   T Horinouchi
 	* numru-misc-0.1.0 released (relase tag: numru-misc-0_1_0)
 
-2008-02-05  S Otsuka
-	* install.rb: for ruby 1.9
+M	ChangeLog
+
+2008-02-05  otsuka 
+bug fix
+
+M	install.rb
+
+2008-02-05  otsuka 
+change for ruby 1.9
+
+M	install.rb
 
+2005-05-13  T Horinouchi  (numru-misc-0_0_6)
 Fri May 13  2005   T Horinouchi
-	* numru-misc-0.0.6 released (relase tag: numru-misc-0_0_6)
-	* keywordopt.rb: KeywordOpt#keys --> public (returns @keys.dup).
+	* keywordopt.rb:
 	  Added KeywordOpt#select_keys.
-Tue Aug 12  2004   T Horinouchi
-	* keywordopt.rb: modified KeywordOptAutoHelp#set to show help
-	  message if 'help'==true.
-Tue Aug 10  2004   T Horinouchi
-	* numru-misc-0.0.5 released (relase tag: numru-misc-0_0_5)
-	* package renamed from misc to numru-misc: started new CVS
-Fri Mar 19  2004   T Horinouchi
-	* emath.rb: basically, a refactoring
-	* install.rb: debug
-Wed Dec 10  2003   T Horinouchi
-	* misc-0.0.4 released
-	* emath.rb: NumRu::EMath --> NumRu::Misc::EMath
-	            Documentation.
-	* misc.rb: documentation update for EMath.
-Tue Oct  7  2003   T Horinouchi
-	* emath.rb: created
-Mon Sep  1  2003   T Horinouchi
-	* misc-0.0.3 released
-	* keywordopt.rb: minor debug of the help messaging in 
-	  KeywordOptAutoHelp#interpret
-Tue Aug 26  2003   T Horinouchi
-	* keywordopt.rb: added class KeywordOptAutoHelp. refined help.
-	  allowed KeywordOpt.new to accept another KeywordOpt.
-Mon Aug 25  2003   T Horinouchi
-	* keywordopt.rb: KeywordOpt#interpret slightly modified
-Mon Aug 25  2003   T Horinouchi
-	* version 0.0.2 released
+
+M	ChangeLog
+M	lib/numru/misc/keywordopt.rb
+
+2005-05-13  T Horinouchi 
+Fri May 13  2005   T Horinouchi
+	* keywordopt.rb: method keys --> public (returns @keys.dup)
+
+M	ChangeLog
+M	lib/numru/misc/keywordopt.rb
+
+2004-08-10  T Horinouchi 
+Initial revision
+
+A	ChangeLog
+A	doc/emath.html
+A	doc/index.html
+A	doc/keywordopt.html
+A	doc/md_iterators.html
+A	doc/misc.html
+A	install.rb
+A	lib/numru/misc.rb
+A	lib/numru/misc/emath.rb
+A	lib/numru/misc/keywordopt.rb
+A	lib/numru/misc/md_iterators.rb
+A	lib/numru/misc/misc.rb
+A	makedoc.csh

data/Gemfile

@@ -0,0 +1,4 @@
+# A sample Gemfile
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -1,7 +1,7 @@
 NumRu::Misc is copyrighted free software by Takeshi Horinouchi and
 GFD Dennou Club (http://www.gfd-dennou.org/).
 
-Copyright 2011 (C) Takeshi Horinouchi and GFD Dennou Club
+Copyright 2011-2015 (C) Takeshi Horinouchi and GFD Dennou Club
 (http://www.gfd-dennou.org/) All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/Rakefile

@@ -1,38 +1,35 @@
-require 'rake/gempackagetask'
-
-NAME = 'numru-misc'
-VER = '0.1.1'
-
-PKG_FILES = FileList[
-  '**',
-  'lib/**/*',
-  'doc/**/*'
-]
+# -* coding: utf-8 -*-
+#require 'rake/testtask'
+#require 'rake/extensiontask'
+require 'rake/packagetask'
+begin
+  require 'bundler/gem_tasks'
+rescue LoadError
+  puts 'If you want to create gem, You must install Bundler'
+end
 
-spec = Gem::Specification.new do |s|
-  s.name             = NAME
-  s.version          = VER
-  s.authors           = ["Takeshi Horinouchi"]
-  s.email            = ['eriko@gfd-dennou.org']
-  s.homepage         = 'http://www.gfd-dennou.org/arch/ruby/products/numru-misc/'
-  s.licenses         = ["Takeshi Horinouchi", "GFD Dennou Club"]
-  s.platform         = Gem::Platform::RUBY
-  s.summary          = %q{Collection of miscellaneous functions and classes to facilitate programming.}
-  s.description      = %q{Miscellaneous functions and classes to help Ruby programming. To be used in other NumRu libraries.}
+require './lib/numru/misc.rb'
+def version
+  NumRu::Misc::VERSION
+end
 
-  s.files            = PKG_FILES.to_a
-  s.require_paths    = ['lib']
-  #s.test_files = Dir.glob("test/*")
-  #s.has_rdoc         = true
-  s.required_ruby_version = Gem::Requirement.new(">= 1.6")
-  s.add_runtime_dependency(%q<narray>, [">= 0"])
-  #s.add_runtime_dependency(%q<narray_miss>, [">= 0"])
-  #s.extra_rdoc_files = ['README']
+=begin
+task :default => :test
+task :test => :compile
+Rake::TestTask.new do |t|
+  t.libs << 'lib' << 'test'
+  #t.test_files = FileList['test/test_*.rb'].exclude('test/test_assoccoords.rb')
+  #t.test_files = FileList['./demo/rubydcloriginal/*.rb']
+end
 
-  #s.extensions << "install.rb"
+Rake::ExtensionTask.new do |ext|
+  ext.name = 'dcl_raw'
+  ext.ext_dir = 'ext/numru'
+  ext.lib_dir = 'lib/numru'
 end
+=end
 
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
-  pkg.need_tar = true
+Rake::PackageTask.new('numru-misc', "#{version}") do |t|
+  t.need_tar_gz = true
+  t.package_files.include `git ls-files`.split("\n")
 end

data/install.rb

@@ -1,8 +1,8 @@
 require 'rbconfig'
 require 'find'
-include Config
+include RbConfig
 
-if CONFIG["MINOR"].to_i > 6 then $rb_18 = true else $rb_18 = false end
+if CONFIG["MINOR"].to_i > 6 || CONFIG["MAJOR"].to_i >= 2 then $rb_18 = true else $rb_18 = false end
 if $rb_18
   require 'fileutils'
 else

data/lib/numru/misc.rb

@@ -1,3 +1,4 @@
+require 'numru/misc/version'
 require 'numru/misc/misc'
 require 'numru/misc/keywordopt'
 require 'numru/misc/md_iterators'

data/lib/numru/misc/emath.rb

@@ -1,30 +1,27 @@
-=begin
-=module NumRu::Misc::EMath
-
-To be included instead of the Math predefined module (or NMath in NArray).
-Unlike Math and NMath, EMath handles unknown classes by calling its
-native instance method (assuming the same name).
-
-Therefore, if included, its function (module method) is used as:
-
-   cos( obj )
-
-and so on. If obj is not of a supported class, EMath calls, obj.cos in
-this case.  (If cos is not a method of obj, then an exception is
-raised.)  Supported classes are Numeric (by Math) and NArray (by
-NMath).  EMath stands for "good Math" (for obvious reason for a
-Japanese).
-
-Note: as for atan2(a,b), a.atan2(b) will be called if a or b
-is not supported. This is the case for all functions that take
-two or more arguments.
-
-=end
-
-require "narray"
 
 module NumRu
   module Misc
+
+    # To be included instead of the Math predefined module (or NMath in NArray).
+    # Unlike Math and NMath, EMath handles unknown classes by calling its
+    # native instance method (assuming the same name).
+    # 
+    # Therefore, if included, its function (module method) is used as:
+    # 
+    #    cos( obj )
+    # 
+    # and so on. If obj is not of a supported class, EMath calls, obj.cos in
+    # this case.  (If cos is not a method of obj, then an exception is
+    # raised.)  Supported classes are Numeric (by Math) and NArray (by
+    # NMath).  EMath stands for "good Math" (for obvious reason for a
+    # Japanese).
+    # 
+    # Note: as for atan2(a,b), a.atan2(b) will be called if a or b
+    # is not supported. This is the case for all functions that take
+    # two or more arguments.
+    # 
+    # require "narray"
+    # require "cmath" if RUBY_VERSION.to_f > 1.8
     module EMath
 
       E = Math::E
@@ -41,7 +38,11 @@ module NumRu
 	def #{func}(*arg)
           case arg[0]
           when Numeric
+        if RUBY_VERSION.to_f > 1.8
+	    CMath.#{func}(*arg)
+        else
 	    Math.#{func}(*arg)
+        end
 	  when NArray
 	    NMath.#{func}(*arg)
 	  else
@@ -64,6 +65,7 @@ if __FILE__ == $0
   p cos( PI )
   p cos( Complex(0, 1) )
   p cos( NArray[0,PI/3,PI/2] )
+  p cos( NArray[ Complex(1,0), Complex(0,1) ] )
   begin
     p cos( "ggg" )
   rescue

data/lib/numru/misc/keywordopt.rb

@@ -1,205 +1,4 @@
-=begin
-==Index
-* ((<class NumRu::Misc::KeywordOpt>))
-* ((<class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt>))
 
-= class NumRu::Misc::KeywordOpt
-
-== Overview
-
-A class to facilitate optional keyword arguments. More specifically,
-it helps the use of a Hash to mimic the keyword argument system.
-With this, you can set default values and description to each 
-keyword argument.
-
-== Classes defined supplementarilly
-
-=== class NumRu::Misc::HelpMessagingException < StandardError
-
-This is for your convenience. See the usage example below.
-
-== Usage example
-
-Suppose that you introduce keyword arguments "flag" and "number"
-to the method "hoge" in a class/module Foo. It can be done as 
-follows:
-
-  require 'numru/misc'  # or, specifically, require 'numru/misc/keywordopt'
-  include NumRu
-
-  class Foo
-    @@opt_hoge = Misc::KeywordOpt.new(
-      ['flag',   false, 'whether or not ...'],
-      ['number', 1,     'number of ...'],
-      ['help',   false, 'show help message']
-    )
-    def hoge(regular_arg1, regular_arg2, options=nil)
-      opt = @@opt_hoge.interpret(options)
-      if opt['help']
-        puts @@opt_hoge.help
-        puts ' Current values='+opt.inspect
-        raise Misc::HelpMessagingException, '** show help message and raise **'
-      end
-      # do what you want below 
-      # (options are set in the Hash opt: opt['flag'] and opt['number'])
-    end
-  end
-
-Here, the options are defined in the class variable @@opt_hoge
-with option names, default values, and descriptions (for help 
-messaging). One can use the method hoge as follows:
-
-  foo = Foo.new
-  ...
-  x = ...
-  y = ...
-  ...
-  foo.hoge( x, y, {'flag'=>true, 'number'=>10} )
-
-Or equivalently,
-
-  foo.hoge( x, y, 'flag'=>true, 'number'=>10 )
-
-because '{}' can be omitted here. 
-
-Tails of options names can be shortened as long as unambiguous:
-
-  foo.hoge( x, y, 'fla'=>true, 'num'=>10 )
-
-
-To show the help message, call
-
-  foo.hoge( x, y, 'help'=>true )
-
-This will cause the following help message printed with the 
-exception HelpMessagingException raised.
-
-   << Description of options >>
-    option name => default value   description:
-     "flag" =>     false   whether or not ...
-     "number" =>   1       number of ...
-     "help" =>     false   show help message
-   Current values={"help"=>true, "number"=>1, "flag"=>false}
-   NumRu::Misc::HelpMessagingException: ** help messaging done **
-          from (irb):78:in "hoge"
-          from (irb):83
-
-Do not affraid to write long descriptions. The help method  
-breaks lines nicely if they are long.
-
-== Class methods
-
----KeywordOpt.new( *args )
-
-    Constructor.
-
-    ARGUMENTS
-    * args : (case 1) arrays of two or three elements: [option name, 
-      default value, description ], or [option name, default value]
-      if you do not want to write descriptions. Option names and 
-      descriptions must be String. (case 2) another KeywordOpt.
-      Cases 1 and 2 can be mixed. 
-
-      When case 2, a link to the other KeywordOpt is kept. Thus, change
-      of values in it is reflected to the current one. However,
-      the link is deleted if values are changed by ((<set>)).
-
-    RETURN VALUE
-    * a KeywordOpt object
-
-    EXAMPLE
-    * case 1
-	opt = Misc::KeywordOpt.new(
-	  ['flag',   false, 'whether or not ...'],
-	  ['help',   false, 'show help message']
-	)
-    * case 2
-        opt = Misc::KeywordOpt.new( optA, optB )
-    * case 1 & 2
-	opt = Misc::KeywordOpt.new(
-	  ['flag',   false, 'whether or not ...'],
-	  optA
-	)
-
-== Methods
----interpret(hash)
-
-    Interprets a hash that specifies option values.
-
-    ARGUMENTS
-    * hash (Hash or nil) : a hash with string keys matching option names 
-      (initializedwhen constructed). The matching is case sensitive and done
-      such that the tail of a option name can be omitted as long as 
-      unambiguous (for example, 'num' for 'number'). 
-      If the argument is nil, the current values are returned.
-      If there are two options like 'max' and 'maxval', to use 
-      a key 'max' (identical to the former paramer) is allowed, although
-      it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)
-
-    RETURN VALUE
-    * a Hash containing the option values (default values overwritten
-      with hash).
-
-    POSSIBLE EXCEPTION
-    * hash has a key that does not match any of the option names.
-    * hash has a key that is ambiguous
-
----set(hash)
-
-    Similar to ((<interpret>)) but changes internal values.
-
-    ARGUMENTS
-    * hash (Hash) : see ((<interpret>)). (Here, nil is not permitted though)
-
-    RETURN VALUE
-    * a Hash containing the values replaced (the ones before calling this 
-      method)
-
-    POSSIBLE EXCEPTION
-    * the argument is not a Hash
-    * others are same as in ((<interpret>))
-
----help
-
-    Returns a help message
-
-    RETURN VALUE
-    * a String describing the option names, default values, and descriptions
-
----[](key)
-
-    Returns a value associated with the key (exact matching unlike interpret)
-
----keys
-
-    Retunrs the keys.
-
----select_existent(hash_or_keys)
-
-    Copies hash_or_keys, exclude ones that are not included in the option
-    (by comparing keys), and returns it. I.e. select only the ones 
-    exsitent. 
-
-    NOTE: ambiguity is not checked, so the resultant value is not 
-    necessarily accepted by ((<interpret>)).
-
-    ARGUMENTS
-    * hash_or_keys (Hash or Array)
-
-    RETURN VALUE
-    * a Hash or Array depending on the class of the argument hash_or_keys
-
-= class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt
-
-Same as ((<class NumRu::Misc::KeywordOpt>)), but the method ((<interpret>))
-shows a help message and raise an exception if option 'help' is provided
-as an argument and is not nil or false 
-((({NumRu::Misc::HelpMessagingException < StandardError}))) 
-or if the arguments cannot be interpreted correctly ((({ArgumentError}))).
-Option 'help' is automatically defined, so you do not have to define it
-yourself.
-
-=end
 
 module NumRu
 
@@ -207,7 +6,119 @@ module NumRu
     class HelpMessagingException < StandardError
     end
 
+    # == Overview
+    # 
+    # A class to facilitate optional keyword arguments. More specifically,
+    # it helps the use of a Hash to mimic the keyword argument system.
+    # With this, you can set default values and description to each 
+    # keyword argument.
+    # 
+    # == Classes defined supplementarilly
+    # 
+    # === class NumRu::Misc::HelpMessagingException < StandardError
+    # 
+    # This is for your convenience. See the usage example below.
+    # 
+    # == Usage example
+    # 
+    # Suppose that you introduce keyword arguments "flag" and "number"
+    # to the method "hoge" in a class/module Foo. It can be done as 
+    # follows:
+    # 
+    #   require 'numru/misc'  # or, specifically, require 'numru/misc/keywordopt'
+    #   include NumRu
+    # 
+    #   class Foo
+    #     @@opt_hoge = Misc::KeywordOpt.new(
+    #       ['flag',   false, 'whether or not ...'],
+    #       ['number', 1,     'number of ...'],
+    #       ['help',   false, 'show help message']
+    #     )
+    #     def hoge(regular_arg1, regular_arg2, options=nil)
+    #       opt = @@opt_hoge.interpret(options)
+    #       if opt['help']
+    #         puts @@opt_hoge.help
+    #         puts ' Current values='+opt.inspect
+    #         raise Misc::HelpMessagingException, '** show help message and raise **'
+    #       end
+    #       # do what you want below 
+    #       # (options are set in the Hash opt: opt['flag'] and opt['number'])
+    #     end
+    #   end
+    # 
+    # Here, the options are defined in the class variable @@opt_hoge
+    # with option names, default values, and descriptions (for help 
+    # messaging). One can use the method hoge as follows:
+    # 
+    #   foo = Foo.new
+    #   ...
+    #   x = ...
+    #   y = ...
+    #   ...
+    #   foo.hoge( x, y, {'flag'=>true, 'number'=>10} )
+    # 
+    # Or equivalently,
+    # 
+    #   foo.hoge( x, y, 'flag'=>true, 'number'=>10 )
+    # 
+    # because '{}' can be omitted here. 
+    # 
+    # Tails of options names can be shortened as long as unambiguous:
+    # 
+    #   foo.hoge( x, y, 'fla'=>true, 'num'=>10 )
+    # 
+    # 
+    # To show the help message, call
+    # 
+    #   foo.hoge( x, y, 'help'=>true )
+    # 
+    # This will cause the following help message printed with the 
+    # exception HelpMessagingException raised.
+    # 
+    #    << Description of options >>
+    #     option name => default value   description:
+    #      "flag" =>     false   whether or not ...
+    #      "number" =>   1       number of ...
+    #      "help" =>     false   show help message
+    #    Current values={"help"=>true, "number"=>1, "flag"=>false}
+    #    NumRu::Misc::HelpMessagingException: ** help messaging done **
+    #           from (irb):78:in "hoge"
+    #           from (irb):83
+    # 
+    # Do not affraid to write long descriptions. The help method  
+    # breaks lines nicely if they are long.
+    # 
     class KeywordOpt
+
+      #   Constructor.
+      # 
+      #   ARGUMENTS
+      #   * args : (case 1) arrays of two or three elements: [option name, 
+      #     default value, description ], or [option name, default value]
+      #     if you do not want to write descriptions. Option names and 
+      #     descriptions must be String. (case 2) another KeywordOpt.
+      #     Cases 1 and 2 can be mixed. 
+      # 
+      #     When case 2, a link to the other KeywordOpt is kept. Thus, change
+      #     of values in it is reflected to the current one. However,
+      #     the link is deleted if values are changed by <b>#set</b>.
+      # 
+      #   RETURN VALUE
+      #   * a KeywordOpt object
+      # 
+      #   EXAMPLE
+      #   * case 1
+      #       opt = Misc::KeywordOpt.new(
+      #         ['flag',   false, 'whether or not ...'],
+      #         ['help',   false, 'show help message']
+      #       )
+      #   * case 2
+      #       opt = Misc::KeywordOpt.new( optA, optB )
+      #   * case 1 & 2
+      #       opt = Misc::KeywordOpt.new(
+      #         ['flag',   false, 'whether or not ...'],
+      #         optA
+      #       )
       def initialize(*args)
 	# USAGE:
 	#    KeywordOpt.new([key,val,description],[key,val,description],..)
@@ -252,6 +163,25 @@ module NumRu
 	end
       end
 
+      #   Interprets a hash that specifies option values.
+    # 
+      #   ARGUMENTS
+      #   * hash (Hash or nil) : a hash with string keys matching option names 
+      #     (initializedwhen constructed). The matching is case sensitive and done
+      #     such that the tail of a option name can be omitted as long as 
+      #     unambiguous (for example, 'num' for 'number'). 
+      #     If the argument is nil, the current values are returned.
+      #     If there are two options like 'max' and 'maxval', to use 
+      #     a key 'max' (identical to the former paramer) is allowed, although
+      #     it matches 'maxval' as well. (Again 'ma' is regarded ambiguous.)
+    # 
+      #   RETURN VALUE
+      #   * a Hash containing the option values (default values overwritten
+      #     with hash).
+    # 
+      #   POSSIBLE EXCEPTION
+      #   * hash has a key that does not match any of the option names.
+      #   * hash has a key that is ambiguous
       def interpret(hash)
 	return @val.dup if hash.nil?
 	##
@@ -278,6 +208,18 @@ module NumRu
 	out
       end
 
+      #   Copies hash_or_keys, exclude ones that are not included in the option
+      #   (by comparing keys), and returns it. I.e. select only the ones 
+      #   exsitent. 
+      # 
+      #   NOTE: ambiguity is not checked, so the resultant value is not 
+      #   necessarily accepted by <b>#interpret</b>.
+      # 
+      #   ARGUMENTS
+      #   * hash_or_keys (Hash or Array)
+      # 
+      #   RETURN VALUE
+      #   * a Hash or Array depending on the class of the argument hash_or_keys
       def select_existent(hash_or_keys)
 	hash_or_keys = hash_or_keys.dup         # not to alter the original
 	len = @val.length
@@ -298,6 +240,18 @@ module NumRu
 	hash_or_keys
       end
 
+      #   Similar to <b>#interpret</b> but changes internal values.
+      # 
+      #   ARGUMENTS
+      #   * hash (Hash) : see <b>#interpret</b>. (Here, nil is not permitted though)
+      # 
+      #   RETURN VALUE
+      #   * a Hash containing the values replaced (the ones before calling this 
+      #     method)
+      # 
+      #   POSSIBLE EXCEPTION
+      #   * the argument is not a Hash
+      #   * others are same as in <b>#interpret</b>
       def set(hash)
 	raise ArgumentError, "not a hash" if !hash.is_a?(Hash)
 	##
@@ -322,15 +276,6 @@ module NumRu
 	replaced
       end
 
-#      def __line_feed(str)
-#	if str.length >= 68
-#	  idx = str[0..67].rindex(/\s/)
-#	  if idx
-#	    str[idx, 1] = "\n\t" 
-#	  end
-#	end
-#	str
-#      end
       def __line_feed(str, len)
 	if str.length >= len
 	  idx = str[0...len].rindex(/\s/)
@@ -342,6 +287,10 @@ module NumRu
       end
       private :__line_feed
 
+      #   Returns a help message
+      # 
+      #   RETURN VALUE
+      #   * a String describing the option names, default values, and descriptions
       def help
 	 "  option name\tdefault value\t# description:\n" +
 	 @keys.collect{|k| 
@@ -349,6 +298,7 @@ module NumRu
 	 }.join("\n")
       end
 
+      # Returns a value associated with the key (exact matching unlike interpret)
       def [](k)
 	v = @val[k]
 	if v.is_a?(KeywordOpt)
@@ -357,17 +307,29 @@ module NumRu
 	v
       end
 
+      # Returns the keys.
       def keys
 	@keys.dup
       end
 
-      ##### protected methods #####
+      ##### protected method
+
       protected
       attr_reader :val, :description
     end
 
     ##################################################
 
+    # 
+    # class NumRu::Misc::KeywordOptAutoHelp < NumRu::Misc::KeywordOpt
+    # 
+    # Same as <b>class NumRu::Misc::KeywordOpt</b>, but the method <b>#interpret</b>
+    # shows a help message and raise an exception if option 'help' is provided
+    # as an argument and is not nil or false 
+    # (NumRu::Misc::HelpMessagingException < StandardError 
+    # or if the arguments cannot be interpreted correctly (ArgumentError).
+    # Option 'help' is automatically defined, so you do not have to define it
+    # yourself.
     class KeywordOptAutoHelp < KeywordOpt
       def initialize(*args)
 	args.push(['help',  false, 'show help message if true'])
@@ -404,7 +366,7 @@ end
 if __FILE__ == $0
   include NumRu
 
-  class Foo
+  class Foo   # :nodoc:
     @@opt_hoge = Misc::KeywordOpt.new(
       ['flag',   false, 'whether or not ...'],
       ['number', 1,     'number of ...'],