multiset 0.5.1 → 0.5.3

data/lib/multiset.rb

@@ -3,70 +3,84 @@
 
 require "enumerator"
 require "multimap"
-VERSION = "0.5.1"
 
-#==概要(Basic information)
+#==Basic information 概要
 #
-# Rubyによる多重集合（マルチセット）の実装です。
-# 通常の集合（Rubyでは"set"ライブラリ）と異なり、多重集合は
-# 同一の要素を複数格納することができます。
-#
-# メソッド名は基本的にSetクラスに合わせてあります。またSetクラスが持つ
-# メソッドの大部分を実装していますが、いくつか未実装なものもあります。
-#
-# Ruby implementation of multiset.
-# Unlike ordinary set(see Ruby documentation for "set" library),
+# A Ruby implementation of multiset.
+# Unlike ordinary set (see Ruby documentation for "set" library),
 # multiset can contain two or more same items.
 #
-# Most methods’ names are same as those of Set class, and all other than
-# a few methods in Set class is implemented on Multiset class.
+# Methods' names are basically consistent with those of Set class.
 #
 # * <code>Set[:a,:b,:c,:b,:b,:c] => #<Set: {:b, :c, :a}></code>
 # * <code>Multiset[:a,:b,:c,:b,:b,:c] => #<Multiset:<tt>#</tt>3 :b, <tt>#</tt>2 :c, <tt>#</tt>1 :a></code>
+#
+# Rubyによる多重集合（マルチセット）の実装です。
+# 通常の集合（Rubyでは"set"ライブラリ）と異なり、多重集合は
+# 同一の要素を複数格納することができます。
+#
+# メソッド名は基本的にSetクラスに合わせてあります。
 
 class Multiset
+  VERSION = "0.5.3"
+
   include Enumerable
   
   #--
   # ============================================================
+  # Constructor
   # コンストラクタ
   # ============================================================
   #++
   
+  # Generates a multiset from items in <code>list</code>.
+  # If <code>list</code> is omitted, returns empty multiset.
+  #
+  # <code>list</code> must be an object including <code>Enumerable</code>.
+  # Otherwise, <code>ArgumentError</code> is raised.
+  #
   # <code>list</code>に含まれる要素からなる多重集合を生成します。
   # <code>list</code>を省略した場合、空の多重集合を生成します。
   #
   # <code>list</code>には<code>Enumerable</code>であるオブジェクトのみ
   # 指定できます。そうでない場合、例外<code>ArgumentError</code>が
   # 発生します。
-  #
-  # Generates a multiset from items in <code>list</code>.
-  # If <code>list</code> is omitted, returns empty multiset.
-  #
-  # <code>list</code> must be <code>Enumerable</code>. If not,
-  # <code>ArgumentError</code> is raised.
   def initialize(list = nil)
     @entries = {}
     if list.kind_of?(Enumerable)
       list.each{ |item| add item }
     elsif list != nil
-      raise ArgumentError, "Item list must include 'Enumerable' module"
+      raise ArgumentError, "Item list must be an instance including 'Enumerable' module"
     end
   end
   
-  # <code>list</code>に含まれる要素からなる多重集合を生成します。
-  # <code>new</code>を用いる場合と異なり、引数の1つ1つが多重集合の要素になります。
+  # Generates a multiset from items in <code>list</code>.
+  # Unlike using <code>Multiset.new</code>, each argument is one item in generated multiset.
   #
-  # 主に多重集合のリテラルを生成するのに用います。
+  # This method is mainly used when you generate a multiset from literals.
   #
-  # Generates a multiset from items in <code>list</code>.
-  # Unlike using <code>new</code>, each argument is one item in generated multiset.
+  # <code>list</code>に含まれる要素からなる多重集合を生成します。
+  # <code>Multiset.new</code>を用いる場合と異なり、引数の1つ1つが多重集合の要素になります。
   #
-  # This method is mainly used when you generate literal of multiset.
+  # 主に、リテラルから多重集合を生成するのに用います。
   def Multiset.[](*list)
     Multiset.new(list)
   end
   
+  # Generates a multiset by converting <code>object</code>.
+  # * If <code>object</code> is an instance of Multiset, returns
+  #   duplicated <code>object</code>.
+  # * If <code>object</code> is not an instance of Multiset and has
+  #   the method <code>each_pair</code>,
+  #   for each pair of two arguments from <code>each_pair</code>,
+  #   the first argument becomes the item in multiset and
+  #   the second argument becomes its number in the multiset.
+  #   See also Hash#to_multiset .
+  # * If <code>object</code> does not have the method <code>each_pair</code>
+  #   and <code>object</code> includes <code>Enumerable</code>, this method
+  #   works the same as Multiset#new .
+  # * Otherwise, <code>ArgumentError</code> is raised.
+  #
   # <code>object</code>を多重集合に変換し生成します。
   # * <code>object</code>がMultisetのインスタンスである場合、
   #   その複製を返します。
@@ -78,19 +92,6 @@ class Multiset
   # * <code>object</code>が<code>each_pair</code>メソッドを持っておらず、
   #   かつ<code>Enumerable</code>である場合は、Multiset#newと同じ結果です。
   # * それ以外の場合は、例外<code>ArgumentError</code>が発生します。
-  # 
-  # Generates a multiset converting <code>object</code>.
-  # * If <code>object</code> is an instance of Multiset, returns
-  #   duplicated <code>object</code>.
-  # * If <code>object</code> is not an instance of Multiset and has
-  #   the method <code>each_pair</code>,
-  #   for each pair of two arguments from <code>each_pair</code>,
-  #   first argument becomes item in multiset and second argument
-  #   becomes its number. See also Hash#to_multiset .
-  # * If <code>object</code> does not have the method <code>each_pair</code>
-  #   and <code>object</code> includes <code>Enumerable</code>, this method
-  #   results equal to Multiset#new .
-  # * Otherwise, <code>ArgumentError</code> is raised.
   def Multiset.parse(object)
     if object.kind_of?(String)
       raise ArgumentError, "Multiset.parse can not parse strings. If you would like to store string lines to a multiset, use Multiset.from_lines(string)."
@@ -111,18 +112,18 @@ class Multiset
     ret
   end
   
-  # 文字列を行単位で区切ってMultisetにします。
-  # 
   # Generates a Multiset from string, separated by lines.
+  # 
+  # 文字列を行単位で区切ってMultisetにします。
   def Multiset.from_lines(str)
     Multiset.new(str.enum_for(:each_line))
   end
   
-  # 文字列が渡された場合は、Multiset.from_linesと同じ挙動。
-  # それ以外の場合は、Multiset.parseと同じ挙動。
-  # 
   # If a string is given, it works as Multiset.from_lines,
   # otherwise as Multiset.parse.
+  # 
+  # 文字列が渡された場合は、Multiset.from_linesと同じ挙動。
+  # それ以外の場合は、Multiset.parseと同じ挙動。
   def Multiset.parse_force(object)
     if object.kind_of?(String)
       Multiset.from_lines(object)
@@ -131,50 +132,52 @@ class Multiset
     end
   end
   
-  # <code>self</code>の複製を生成して返します。
-  #
   # Returns duplicated <code>self</code>.
+  #
+  # <code>self</code>の複製を生成して返します。
   def dup
     @entries.to_multiset
   end
   
-  # <code>self</code>を<code>Hash</code>に変換して返します。
-  # 生成されるハッシュの構造については、Hash#to_multisetをご覧下さい。
-  #
   # Converts <code>self</code> to a <code>Hash</code>.
   # See Hash#to_multiset about format of generated hash.
+  #
+  # <code>self</code>を<code>Hash</code>に変換して返します。
+  # 生成されるハッシュの構造については、Hash#to_multisetをご覧下さい。
   def to_hash
     @entries.dup
   end
   
   #--
   # ============================================================
+  # Basic functions such as converting into other types
   # 別の型への変換、基本的な関数など
   # ============================================================
   #++
   
-  # <code>self</code>を通常の集合（Ruby標準添付の<code>Set</code>）に
-  # 変換したものを返します。
-  #
-  # このメソッドを呼び出すと、<code>require "set"</code>が行われます。
-  #
-  # なおSetをMultisetに変換するには、<code>Multiset.new(instance_of_set)</code>で
-  # 可能です。
-  #
   # Converts <code>self</code> to ordinary set
   # (The <code>Set</code> class attached to Ruby by default).
   #
   # <code>require "set"</code> is performed when this method is called.
   #
-  # To convert Set to Multiset, use <code>Multiset.new(instance_of_set)</code>.
+  # Note: To convert an instance of Set to Multiset, use
+  # <code>Multiset.new(instance_of_set)</code>.
+  #
+  # <code>self</code>を通常の集合（Ruby標準添付の<code>Set</code>）に
+  # 変換したものを返します。
+  #
+  # このメソッドを呼び出すと、<code>require "set"</code>が行われます。
+  #
+  # 注：逆に、SetのインスタンスをMultisetに変換するには、
+  # <code>Multiset.new(instance_of_set)</code>で可能です。
   def to_set
     require "set"
     Set.new(@entries.keys)
   end
   
-  # <code>self</code>を配列に変換して返します。
-  #
   # Converts <code>self</code> to an array.
+  #
+  # <code>self</code>を配列に変換して返します。
   def to_a
     ret = []
     @entries.each_pair do |item, count|
@@ -201,15 +204,16 @@ class Multiset
   
   #--
   # ============================================================
+  # Basic operations such as ones required for other methods
   # 基本操作（他のメソッドを定義するのに頻出するメソッドなど）
   # ============================================================
   #++
   
-  # <code>self</code>の内容を<code>other</code>のものに置き換えます。
-  # <code>self</code>を返します。
-  #
   # Replaces <code>self</code> by <code>other</code>.
   # Returns <code>self</code>.
+  #
+  # <code>self</code>の内容を<code>other</code>のものに置き換えます。
+  # <code>self</code>を返します。
   def replace(other)
     @entries.clear
     other.each_pair do |item, count|
@@ -218,54 +222,54 @@ class Multiset
     self
   end
   
-  # <code>self</code>に含まれている要素数を返します。
-  #
   # Returns number of all items in <code>self</code>.
+  #
+  # <code>self</code>に含まれている要素数を返します。
   def size
     @entries.inject(0){ |sum, item| sum += item[1] }
   end
   alias length size
   
-  # <code>self</code>に要素がないかどうかを返します。
-  #
   # Returns whether <code>self</code> has no item.
+  #
+  # <code>self</code>に要素がないかどうかを返します。
   def empty?
     @entries.empty?
   end
   
-  # <code>self</code>に含まれている要素（重複は除く）からなる配列を返します。
-  #
   # Returns an array with all items in <code>self</code>, without duplication.
+  #
+  # <code>self</code>に含まれている要素（重複は除く）からなる配列を返します。
   def items
     @entries.keys
   end
   
-  # <code>self</code>の要素をすべて削除します。
-  # <code>self</code>を返します。
-  #
   # Deletes all items in <code>self</code>.
   # Returns <code>self</code>.
+  #
+  # <code>self</code>の要素をすべて削除します。
+  # <code>self</code>を返します。
   def clear
     @entries.clear
     self
   end
   
-  # <code>item</code>が<code>self</code>中に含まれているかを返します。
-  #
   # Returns whether <code>self</code> has <code>item</code>.
+  #
+  # <code>item</code>が<code>self</code>中に含まれているかを返します。
   def include?(item)
     @entries.has_key?(item)
   end
   alias member? include?
   
-  # <code>self</code>の全要素を（重複を許して）並べた文字列を返します。
-  # 要素間の区切りは<code>delim</code>の値を用い、
-  # 各要素の表示形式は与えられたブロックの返り値（なければObject#inspect）を用います。
-  #
   # Lists all items with duplication in <code>self</code>.
   # Items are deliminated with <code>delim</code>, and items are
   # converted to string in the given block.
   # If block is omitted, Object#inspect is used.
+  #
+  # <code>self</code>の全要素を（重複を許して）並べた文字列を返します。
+  # 要素間の区切りは<code>delim</code>の値を用い、
+  # 各要素の表示形式は与えられたブロックの返り値（なければObject#inspect）を用います。
   def listing(delim = "\n")
     buf = ''
     init = true
@@ -280,14 +284,14 @@ class Multiset
     buf
   end
   
-  # <code>self</code>の要素と要素数の組を並べた文字列を返します。
-  # 要素間の区切りは<code>delim</code>の値を用い、
-  # 各要素の表示形式は与えられたブロックの返り値（なければObject#inspect）を用います。
-  #
   # Lists all items without duplication and its number in <code>self</code>.
   # Items are deliminated with <code>delim</code>, and items are
   # converted to string in the given block.
   # If block is omitted, Object#inspect is used.
+  #
+  # <code>self</code>の要素と要素数の組を並べた文字列を返します。
+  # 要素間の区切りは<code>delim</code>の値を用い、
+  # 各要素の表示形式は与えられたブロックの返り値（なければObject#inspect）を用います。
   def to_s(delim = "\n")
     buf = ''
     init = true
@@ -312,21 +316,22 @@ class Multiset
   
   #--
   # ============================================================
-  # 要素数の更新
+  # The number of elements in a multiset
+  # マルチセットの要素数
   # ============================================================
   #++
   
-  # <code>self</code>中に含まれる<code>item</code>の個数を返します。
-  # 引数を指定しない場合は、Multiset#sizeと同じです。
-  # ブロックを指定することもでき、その場合は（重複しない）各要素をブロックに与え、
-  # 条件を満たした（結果が真であった）要素がMultiset内にいくつ入っているかを数えます。
-  #
   # Returns number of <code>item</code>s in <code>self</code>.
   # If the <code>item</code> is omitted, the value is same as Multiset#size.
   # If a block is given, each element (without duplication) is given to
   # the block, and returns the number of elements (including duplication)
   # that returns true in the block.
-  # 
+  #
+  # <code>self</code>中に含まれる<code>item</code>の個数を返します。
+  # 引数を指定しない場合は、Multiset#sizeと同じです。
+  # ブロックを指定することもでき、その場合は（重複しない）各要素をブロックに与え、
+  # 条件を満たした（結果が真であった）要素がMultiset内にいくつ入っているかを数えます。
+  #
   # :call-seq:
   #   count(item)
   #   count{ |item| ... }
@@ -353,13 +358,13 @@ class Multiset
     end
   end
   
+  # Sets the number of <code>item</code> in <code>self</code> as <code>number</code>.
+  # If <code>number</code> is negative, it is considered as <code>number = 0</code>.
+  # Returns <code>self</code> if succeeded, <code>nil</code> otherwise.
+  #
   # <code>self</code>に含まれる<code>item</code>の個数を<code>number</code>個にします。
   # <code>number</code>が負の数であった場合は、<code>number = 0</code>とみなします。
   # 成功した場合は<code>self</code>を、失敗した場合は<code>nil</code>を返します。
-  #
-  # Sets number of <code>item</code> to <code>number</code> in <code>self</code>.
-  # If <code>number</code> is negative, treats as <code>number = 0</code>.
-  # Returns <code>self</code> if succeeded, <code>nil</code> otherwise.
   def renew_count(item, number)
     return nil if number == nil
     n = number.to_i
@@ -371,11 +376,11 @@ class Multiset
     self
   end
   
-  # <code>self</code>に、<code>addcount</code>個の<code>item</code>を追加します。
-  # 成功した場合は<code>self</code>を、失敗した場合は<code>nil</code>を返します。
-  #
   # Adds <code>addcount</code> number of <code>item</code>s to <code>self</code>.
   # Returns <code>self</code> if succeeded, or <code>nil</code> if failed.
+  #
+  # <code>self</code>に、<code>addcount</code>個の<code>item</code>を追加します。
+  # 成功した場合は<code>self</code>を、失敗した場合は<code>nil</code>を返します。
   def add(item, addcount = 1)
     return nil if addcount == nil
     a = addcount.to_i
@@ -384,12 +389,12 @@ class Multiset
   end
   alias << add
   
-  # <code>self</code>から、<code>delcount</code>個の<code>item</code>を削除します。
-  # 成功した場合は<code>self</code>を、失敗した場合は<code>nil</code>を返します。
-  #
   # Deletes <code>delcount</code> number of <code>item</code>s
   # from <code>self</code>.
   # Returns <code>self</code> if succeeded, <code>nil</code> otherwise.
+  #
+  # <code>self</code>から、<code>delcount</code>個の<code>item</code>を削除します。
+  # 成功した場合は<code>self</code>を、失敗した場合は<code>nil</code>を返します。
   def delete(item, delcount = 1)
     return nil if delcount == nil || !self.include?(item)
     d = delcount.to_i
@@ -397,11 +402,11 @@ class Multiset
     self.renew_count(item, self.count(item) - d)
   end
   
-  # <code>self</code>に含まれる<code>item</code>をすべて削除します。
-  # <code>self</code>を返します。
-  #
   # Deletes all <code>item</code>s in <code>self</code>.
   # Returns <code>self</code>.
+  #
+  # <code>self</code>に含まれる<code>item</code>をすべて削除します。
+  # <code>self</code>を返します。
   def delete_all(item)
     @entries.delete(item)
     self
@@ -409,22 +414,23 @@ class Multiset
   
   #--
   # ============================================================
+  # Relationships about inclusions
   # 包含関係の比較
   # ============================================================
   #++
   
-  # <code>self</code>と<code>other</code>が持つすべての要素（重複なし）について
-  # 繰り返し、ブロックの返り値が偽であるものが存在すればその時点でfalseを返します。
-  # すべての要素について真であればtrueを返します。
-  #
-  # このメソッドはsuperset?、subset?、== のために定義されています。
-  #
   # Iterates for each item in <code>self</code> and <code>other</code>,
   # without duplication. If the given block returns false, then iteration
   # immediately ends and returns false.
   # Returns true if the given block returns true for all of iteration.
   # 
   # This method is defined for methods superset?, subset?, ==.
+  #
+  # <code>self</code>と<code>other</code>が持つすべての要素（重複なし）について
+  # 繰り返し、ブロックの返り値が偽であるものが存在すればその時点でfalseを返します。
+  # すべての要素について真であればtrueを返します。
+  #
+  # このメソッドはsuperset?、subset?、== のために定義されています。
   def compare_set_with(other) # :nodoc: :yields: number_in_self, number_in_other
     (self.items | other.items).each do |item|
       return false unless yield(self.count(item), other.count(item))
@@ -432,9 +438,13 @@ class Multiset
     true
   end
   
-  # <code>self</code>が<code>other</code>を含んでいるかどうかを返します。
+  # Returns whether <code>self</code> is a superset of <code>other</code>,
+  # that is, for any item, the number of it in <code>self</code> is
+  # equal to or larger than that in <code>other</code>.
   # 
-  # Returns whether <code>self</code> is a superset of <code>other</code>.
+  # <code>self</code>が<code>other</code>を含んでいるかどうかを返します。
+  # すなわち、いかなる要素についても、それが<code>self</code>に含まれている
+  # 個数が<code>other</code>に含まれている数以上であるかを返します。
   def superset?(other)
     unless other.instance_of?(Multiset)
       raise ArgumentError, "Argument must be a Multiset"
@@ -442,20 +452,26 @@ class Multiset
     compare_set_with(other){ |s, o| s >= o }
   end
   
+  # Returns whether <code>self</code> is a proper superset of <code>other</code>,
+  # that is, it returns true if superset? is satisfied and
+  # <code>self</code> is not equal to <code>other</code>.
+  #
   # <code>self</code>が<code>other</code>を真に含んでいるかどうかを返します。
-  # 「真に」とは、両者が一致する場合は含めないことを示します。
-  # 
-  # Returns whether <code>self</code> is a proper superset of <code>other</code>.
+  # すなわち、 superset? の条件に加えて両者が一致しなければ真となります。
   def proper_superset?(other)
     unless other.instance_of?(Multiset)
       raise ArgumentError, "Argument must be a Multiset"
     end
     self.superset?(other) && self != other
   end
-  
-  # <code>self</code>が<code>other</code>に含まれているかどうかを返します。
+
+  # Returns whether <code>self</code> is a subset of <code>other</code>,
+  # that is, for any item, the number of it in <code>self</code> is
+  # equal to or smaller than that in <code>other</code>.
   # 
-  # Returns whether <code>self</code> is a subset of <code>other</code>.
+  # <code>self</code>が<code>other</code>を含んでいるかどうかを返します。
+  # すなわち、いかなる要素についても、それが<code>self</code>に含まれている
+  # 個数が<code>other</code>に含まれている数以下であるかを返します。
   def subset?(other)
     unless other.instance_of?(Multiset)
       raise ArgumentError, "Argument must be a Multiset"
@@ -463,10 +479,12 @@ class Multiset
     compare_set_with(other){ |s, o| s <= o }
   end
   
+  # Returns whether <code>self</code> is a proper subset of <code>other</code>,
+  # that is, it returns true if subset? is satisfied and
+  # <code>self</code> is not equal to <code>other</code>.
+  #
   # <code>self</code>が<code>other</code>に真に含まれているかどうかを返します。
-  # 「真に」とは、両者が一致する場合は含めないことを示します。
-  # 
-  # Returns whether <code>self</code> is a proper subset of <code>other</code>.
+  # すなわち、 subset? の条件に加えて両者が一致しなければ真となります。
   def proper_subset?(other)
     unless other.instance_of?(Multiset)
       raise ArgumentError, "Argument must be a Multiset"
@@ -474,9 +492,9 @@ class Multiset
     self.subset?(other) && self != other
   end
   
-  # <code>self</code>が<code>other</code>と等しいかどうかを返します。
-  #
   # Returns whether <code>self</code> is equal to <code>other</code>.
+  #
+  # <code>self</code>が<code>other</code>と等しいかどうかを返します。
   def ==(other)
     return false unless other.instance_of?(Multiset)
     compare_set_with(other){ |s, o| s == o }
@@ -484,13 +502,14 @@ class Multiset
   
   #--
   # ============================================================
+  # Other operations for two multisets
   # その他、2つのMultisetについての処理
   # ============================================================
   #++
   
-  # <code>self</code>と<code>other</code>の要素を合わせた多重集合を返します。
+  # Returns a multiset merging <code>self</code> and <code>other</code>.
   #
-  # Returns merged multiset of <code>self</code> and <code>other</code>.
+  # <code>self</code>と<code>other</code>の要素を合わせた多重集合を返します。
   def merge(other)
     ret = self.dup
     other.each_pair do |item, count|
@@ -500,11 +519,13 @@ class Multiset
   end
   alias + merge
   
-  # <code>self</code>に<code>other</code>の要素を追加します。
-  # <code>self</code>を返します。
-  #
   # Merges <code>other</code> to <code>self</code>.
+  # See also Multiset#merge .
   # Returns <code>self</code>.
+  #
+  # <code>self</code>に<code>other</code>の要素を追加します。
+  # Multiset#merge も参照してください。
+  # <code>self</code>を返します。
   def merge!(other)
     other.each_pair do |item, count|
       self.add(item, count)
@@ -512,9 +533,13 @@ class Multiset
     self
   end
   
-  # <code>self</code>から<code>other</code>の要素を取り除いた多重集合を返します。
+  # Returns a multiset such that items in <code>other</code> are removed from <code>self</code>,
+  # where 'removed' means that, for each item in <code>other</code>,
+  # the items of the number in <code>other</code> are removed from <code>self</code>.
   #
-  # Returns multiset such that items in <code>other</code> are removed from <code>self</code>.
+  # <code>self</code>から<code>other</code>の要素を取り除いた多重集合を返します。
+  # ここで「取り除く」ことは、<code>other</code>の各要素について、
+  # それを<code>other</code>にある個数分<code>self</code>から取り除くことをいいます。
   def subtract(other)
     ret = self.dup
     other.each_pair do |item, count|
@@ -524,11 +549,13 @@ class Multiset
   end
   alias - subtract
   
-  # <code>self</code>から<code>other</code>の要素を削除します。
-  # <code>self</code>を返します。
-  #
   # Removes items in <code>other</code> from <code>self</code>.
+  # See also Multiset#subtract .
   # Returns <code>self</code>.
+  #
+  # <code>self</code>から<code>other</code>の要素を削除します。
+  # Multiset#subtract も参照してください。
+  # <code>self</code>を返します。
   def subtract!(other)
     other.each_pair do |item, count|
       self.delete(item, count)
@@ -536,9 +563,13 @@ class Multiset
     self
   end
   
-  # <code>self</code>と<code>other</code>の積集合からなる多重集合を返します。
+  # Returns the intersection of <code>self</code> and <code>other</code>,
+  # that is, for each item both in <code>self</code> and <code>other</code>,
+  # the multiset includes it in the smaller number of the two.
   #
-  # Returns intersection of <code>self</code> and <code>other</code>.
+  # <code>self</code>と<code>other</code>の積集合からなる多重集合を返します。
+  # すなわち、<code>self</code>と<code>other</code>の両方に存在する要素について、
+  # 少ないほうの個数を持った多重集合を返します。
   def &(other)
     ret = Multiset.new
     (self.items & other.items).each do |item|
@@ -547,9 +578,13 @@ class Multiset
     ret
   end
   
-  # <code>self</code>と<code>other</code>の和集合からなる多重集合を返します。
+  # Returns the union of <code>self</code> and <code>other</code>,
+  # that is, for each item either or both in <code>self</code> and <code>other</code>,
+  # the multiset includes it in the larger number of the two.
   #
-  # Returns union of <code>self</code> and <code>other</code>.
+  # <code>self</code>と<code>other</code>の和集合からなる多重集合を返します。
+  # すなわち、<code>self</code>と<code>other</code>の少なくとも一方に存在する要素について、
+  # 多いほうの個数を持った多重集合を返します。
   def |(other)
     ret = self.dup
     other.each_pair do |item, count|
@@ -560,28 +595,30 @@ class Multiset
   
   #--
   # ============================================================
+  # Processes for single multiset
   # 1つのMultisetの各要素についての処理
   # ============================================================
   #++
   
-  # <code>self</code>に含まれるすべての要素について繰り返します。
-  # <code>self</code>を返します。
-  # ブロックが与えられていない場合、Enumeratorを返します。
-  # 
-  # このメソッドは Enumerable#each の挙動に合わせ、同じ要素を何度もブロックに
-  # 渡すため、効率が悪いです。Multiset#each_item, Multiset#each_pairの利用もご検討下さい。
-  # 例えば「"a"が100個入ったMultiset」をeachで繰り返すと100回の処理が行われますが、
-  # each_pairなら1回で済みます。
-  # 
   # Iterates for each item in <code>self</code>.
   # Returns <code>self</code>.
   # An Enumerator will be returned if no block is given.
   # 
   # This method is ineffective since the same element in the Multiset
-  # can be given to the block for many times, same as the behavior of Enumerable#each.
+  # can be given to the block for many times,
+  # so that it behaves the same as Enumerable#each.
   # Please consider using Multiset#each_item or Multiset#each_pair: for example,
   # a Multiset with 100 times "a" will call the given block for 100 times for Multiset#each,
   # while only once for Multiset#each_pair.
+  #
+  # <code>self</code>に含まれるすべての要素について繰り返します。
+  # <code>self</code>を返します。
+  # ブロックが与えられていない場合、Enumeratorを返します。
+  # 
+  # このメソッドは Enumerable#each の挙動に合わせ、同じ要素を何度もブロックに
+  # 渡すため、効率が悪いです。Multiset#each_item, Multiset#each_pairの利用もご検討下さい。
+  # 例えば「"a"が100個入ったMultiset」をeachで繰り返すと100回の処理が行われますが、
+  # each_pairなら1回で済みます。
   def each
     if block_given?
       @entries.each_pair do |item, count|
@@ -593,13 +630,13 @@ class Multiset
     end
   end
   
-  # <code>self</code>に含まれるすべての要素について、重複を許さずに繰り返します。
-  # <code>self</code>を返します。
-  # ブロックが与えられていない場合、Enumeratorを返します。
-  #
   # Iterates for each item in <code>self</code>, without duplication.
   # Returns <code>self</code>.
   # An Enumerator will be returned if no block is given.
+  #
+  # <code>self</code>に含まれるすべての要素について、重複を許さずに繰り返します。
+  # <code>self</code>を返します。
+  # ブロックが与えられていない場合、Enumeratorを返します。
   def each_item(&block) # :yields: item
     if block
       @entries.each_key(&block)
@@ -609,13 +646,13 @@ class Multiset
     end
   end
   
-  # <code>self</code>に含まれるすべての要素（重複なし）とその個数について繰り返します。
-  # <code>self</code>を返します。
-  # ブロックが与えられていない場合、Enumeratorを返します。
-  #
   # Iterates for each pair of (non-duplicated) item and its number in <code>self</code>.
   # Returns <code>self</code>.
   # An Enumerator will be returned if no block is given.
+  #
+  # <code>self</code>に含まれるすべての要素（重複なし）とその個数について繰り返します。
+  # <code>self</code>を返します。
+  # ブロックが与えられていない場合、Enumeratorを返します。
   def each_with_count(&block) # :yields: item, count
     if block
       @entries.each_pair(&block)
@@ -626,11 +663,11 @@ class Multiset
   end
   alias :each_pair :each_with_count
   
-  # <code>self</code>の各要素（重複なし）をブロックに与え、返り値を集めたものからなる
-  # 多重集合を生成します。
-  # 
   # Gives all items in <code>self</code> (without duplication) to given block,
   # and generates a new multiset whose values are returned value from the block.
+  #
+  # <code>self</code>の各要素（重複なし）をブロックに与え、返り値を集めたものからなる
+  # 多重集合を生成します。
   def map # :yields: item
     ret = Multiset.new
     @entries.each_pair do |item, count|
@@ -640,25 +677,25 @@ class Multiset
   end
   alias collect map
   
-  # Multiset#mapと同様ですが、結果として生成される多重集合で<code>self</code>が
-  # 置き換えられます。<code>self</code>を返します。
-  # 
-  # Same as Multiset#map, but replaces <code>self</code> by resulting multiset.
+  # Same as Multiset#map, except that <code>self</code> is replaced by the resulted multiset.
   # Returns <code>self</code>.
+  #
+  # Multiset#mapと同様の処理を行いますが、結果として生成される多重集合で<code>self</code>が
+  # 置き換えられます。<code>self</code>を返します。
   def map!(&block) # :yields: item
     self.replace(self.map(&block))
     self
   end
   alias collect! map!
   
-  # <code>self</code>の要素（重複なし）とその個数の組をブロックに与えます。
-  # ブロックから2要素の配列を受け取り、前者を要素、後者をその個数とした
-  # 多重集合を生成します。
-  # 
-  # Gives all pairs of (non-duplicate) items and their numbers in <code>self</code> to
+  # Gives all pairs of (non-duplicated) items and their numbers in <code>self</code> to
   # given block. The block must return an array of two items.
   # Generates a new multiset whose values and numbers are the first and
   # second item of returned array, respectively.
+  #
+  # <code>self</code>の要素（重複なし）とその個数の組をブロックに与えます。
+  # ブロックから2要素の配列を受け取り、前者を要素、後者をその個数とした
+  # 多重集合を生成します。
   def map_with
     ret = Multiset.new
     @entries.each_pair do |item, count|
@@ -669,11 +706,11 @@ class Multiset
   end
   alias collect_with map_with
   
+  # Same as Multiset#map_with, except that <code>self</code> by
+  # the resulted multiset. Returns <code>self</code>.
+  # 
   # Multiset#map_withと同様ですが、結果として生成される多重集合で
   # <code>self</code>が置き換えられます。<code>self</code>を返します。
-  # 
-  # Same as Multiset#map_with, but replaces <code>self</code> by
-  # resulting multiset. Returns <code>self</code>.
   def map_with!
     self.to_hash.each_pair do |item, count|
       self.delete(item, count)
@@ -684,13 +721,13 @@ class Multiset
   end
   alias collect_with! map_with!
   
+  # Returns one item in <code>self</code> at random
+  # in the same probability.
+  # Returns <code>nil</code> in case the multiset is empty.
+  #
   # <code>self</code>の要素を無作為に1つ選んで返します。
   # すべての要素は等確率で選ばれます。
-  # 空のmultisetに対して呼び出した場合は<code>nil</code>を返します。
-  #
-  # Returns one item in <code>self</code> randomly.
-  # All items are selected with the same probability.
-  # Returns <code>nil</code> in case the multiset is empty.
+  # 空のMultisetに対して呼び出した場合は<code>nil</code>を返します。
   def sample
     return nil if empty?
     pos = Kernel.rand(self.size)
@@ -701,9 +738,9 @@ class Multiset
   end
   alias :rand :sample
   
-  # <code>self</code>中に含まれる多重集合を平滑化したものを返します。
-  #
   # Generates a multiset such that multisets in <code>self</code> are flattened.
+  #
+  # <code>self</code>中に含まれる多重集合を平滑化したものを返します。
   def flatten
     ret = Multiset.new
     self.each do |item|
@@ -716,13 +753,13 @@ class Multiset
     ret
   end
   
-  # <code>self</code>中に含まれる多重集合を平滑化します。
-  # 平滑化した多重集合が1つでもあれば<code>self</code>を、
-  # そうでなければ<code>nil</code>を返します。
-  #
   # Flattens multisets in <code>self</code>.
   # Returns <code>self</code> if any item is flattened,
   # <code>nil</code> otherwise.
+  #
+  # <code>self</code>中に含まれる多重集合を平滑化します。
+  # 平滑化した多重集合が1つでもあれば<code>self</code>を、
+  # そうでなければ<code>nil</code>を返します。
   def flatten!
     ret = nil
     self.to_a.each do |item|
@@ -735,11 +772,11 @@ class Multiset
     ret
   end
   
+  # Gives all items in <code>self</code> (without duplication) to given block,
+  # and returns a multiset collecting the items such that the block returns false.
+  #
   # ブロックに<code>self</code>の要素（重複なし）を順次与え、
   # 結果が偽であった要素のみを集めたMultisetを返します。
-  #
-  # Gives all items in <code>self</code> (without duplication) to given block,
-  # and returns a multiset collecting the items whose results in the block are false.
   def reject
     ret = Multiset.new
     @entries.each_pair do |item, count|
@@ -748,11 +785,11 @@ class Multiset
     ret
   end
   
+  # Gives all pairs of (non-duplicated) items and counts in <code>self</code> to given block,
+  # and returns a multiset collecting the items such that the block returns false.
+  #
   # ブロックに<code>self</code>の要素（重複なし）と個数の組を順次与え、
   # 結果が偽であった要素のみを集めたMultisetを返します。
-  #
-  # Gives all pairs of (non-duplicate) items and counts in <code>self</code> to given block,
-  # and returns a multiset collecting the items whose results in the block are false.
   def reject_with
     ret = Multiset.new
     @entries.each_pair do |item, count|
@@ -761,9 +798,9 @@ class Multiset
     ret
   end
   
-  # Multiset#delete_ifと同じですが、要素が1つも削除されなければ<code>nil</code>を返します。
+  # Same as Multiset#delete_if except that this returns <code>nil</code> if no item is deleted.
   #
-  # Same as Multiset#delete_if, but returns <code>nil</code> if no item is deleted.
+  # Multiset#delete_ifと似ますが、要素が1つも削除されなければ<code>nil</code>を返します。
   def reject!
     ret = nil
     @entries.each_pair do |item, count|
@@ -775,13 +812,13 @@ class Multiset
     ret
   end
   
+  # Gives all items in <code>self</code> (without duplication) to given block,
+  # and deletes the items such that the block returns true.
+  # Returns <code>self</code>.
+  #
   # ブロックに<code>self</code>の要素（重複なし）を順次与え、
   # 結果が真であった要素をすべて削除します。
   # <code>self</code>を返します。
-  #
-  # Gives all items in <code>self</code> (without duplication) to given block,
-  # and deletes that item if the block returns true.
-  # Returns <code>self</code>.
   def delete_if
     @entries.each_pair do |item, count|
       self.delete_all(item) if yield(item)
@@ -789,13 +826,13 @@ class Multiset
     self
   end
   
+  # Gives each pair of (non-duplicated) item and its number to given block,
+  # and deletes those items such that the block returns true.
+  # Returns <code>self</code>.
+  #
   # <code>self</code>に含まれるすべての要素（重複なし）とその個数について、
   # その組をブロックに与え、結果が真であった要素をすべて削除します。
   # <code>self</code>を返します。
-  #
-  # Gives each pair of (non-duplicate) item and its number to given block,
-  # and deletes those items if the block returns true.
-  # Returns <code>self</code>.
   def delete_with
     @entries.each_pair do |item, count|
       @entries.delete(item) if yield(item, count)
@@ -803,12 +840,12 @@ class Multiset
     self
   end
   
+  # Classify items in <code>self</code> by returned value from block.
+  # Returns a Multimap whose values are associated with keys, where
+  # the keys are the returned value from given block.
+  #
   # <code>self</code>の要素を、与えられたブロックからの返り値によって分類します。
   # ブロックからの返り値をキーとして値を対応付けたMultimapを返します。
-  #
-  # Classify items in <code>self</code> by returned value from block.
-  # Returns a Multimap whose values are associated with keys. Keys
-  # are defined by returned value from given block.
   def group_by
     ret = Multimap.new
     @entries.each_pair do |item, count|
@@ -818,9 +855,10 @@ class Multiset
   end
   alias :classify :group_by
   
-  # Multiset#group_byと同様ですが、ブロックには要素とその個数の組が与えられます。
+  # Same as Multiset#group_by except that the pairs of (non-duplicated) items and
+  # their counts are given to block.
   #
-  # Same as Multiset#group_by, but the pairs of (non-duplicate) items and their counts are given to block.
+  # Multiset#group_byと同様ですが、ブロックには要素とその個数の組が与えられます。
   def group_by_with
     ret = Multimap.new
     @entries.each_pair do |item, count|
@@ -830,17 +868,17 @@ class Multiset
   end
   alias :classify_with :group_by_with
   
-  # ブロックに<code>self</code>の要素（重複なし）を順次与え、
-  # 最初に結果が真であった要素を返します。
-  # 見つからなかった場合は、ifnoneが指定されている場合は ifnone.call し、
-  # そうでなければnilを返します。
-  # ブロックを与えなかった場合、そのためのEnumeratorを返します。
-  #
   # Gives all items in <code>self</code> (without duplication) to given block,
   # and returns the first item that makes true the result of the block.
   # If none of the items make it true, ifnone.call is executed if ifnone is specified,
   # otherwise nil is returned.
   # If no block is given, corresponding Enumerator is returned.
+  #
+  # ブロックに<code>self</code>の要素（重複なし）を順次与え、
+  # 最初に結果が真であった要素を返します。
+  # 見つからなかった場合は、ifnoneが指定されている場合は ifnone.call し、
+  # そうでなければnilを返します。
+  # ブロックを与えなかった場合、そのためのEnumeratorを返します。
   def find(ifnone = nil, &block) # :yields: item
     if block
       find_(ifnone, &block)
@@ -858,9 +896,10 @@ class Multiset
   end
   private :find_
   
-  # Multiset#findと同じですが、ブロックには<code>self</code>の要素とその個数の組が与えられます。
+  # The same as Multiset#find except that the pairs of (non-duplicated) items and
+  # their counts are given to the block.
   #
-  # The same as Multiset#find, but pairs of (non-duplicate) items and their counts are given to the block.
+  # Multiset#findと似ますが、ブロックには<code>self</code>の要素とその個数の組が与えられます。
   def find_with(ifnone = nil, &block) # :yields: item, count
     if block
       find_with_(ifnone, &block)
@@ -878,13 +917,13 @@ class Multiset
   end
   private :find_with_
   
-  # ブロックに<code>self</code>の要素（重複なし）を順次与え、
-  # 結果が真であった要素を集めた多重集合を返します。
-  # ブロックを与えなかった場合、そのためのEnumeratorを返します。
-  #
   # Gives all items in <code>self</code> (without duplication) to given block,
   # and returns the Multiset by items that makes true the result of the block.
   # If no block is given, corresponding Enumerator is returned.
+  #
+  # ブロックに<code>self</code>の要素（重複なし）を順次与え、
+  # 結果が真であった要素を集めた多重集合を返します。
+  # ブロックを与えなかった場合、そのためのEnumeratorを返します。
   def find_all(&block) # :yields: item
     if block
       find_all_(&block)
@@ -903,9 +942,10 @@ class Multiset
   end
   private :find_all_
   
-  # Multiset#find_allと同じですが、ブロックには<code>self</code>の要素とその個数の組が与えられます。
+  # The same as Multiset#find_all except that the pairs of (non-duplicated) items and
+  # their counts are given to the block.
   #
-  # The same as Multiset#find_all, but pairs of (non-duplicate) items and their counts are given to the block.
+  # Multiset#find_allと似ますが、ブロックには<code>self</code>の要素とその個数の組が与えられます。
   def find_all_with(&block) # :yields: item, count
     if block
       find_all_with_(&block)
@@ -924,11 +964,11 @@ class Multiset
   end
   private :find_all_with_
   
-  # <code>pattern</code>の条件を満たした（<code>pattern</code> === item）要素のみを集めた多重集合を返します。
-  # ブロックが与えられている場合は、さらにその結果を適用した結果を返します。
-  #
   # Collects items in <code>self</code> satisfying <code>pattern</code> (<code>pattern</code> === item).
   # If a block is given, the items are converted by the result of the block.
+  #
+  # <code>pattern</code>の条件を満たした（<code>pattern</code> === item）要素のみを集めた多重集合を返します。
+  # ブロックが与えられている場合は、さらにその結果を適用した結果を返します。
   def grep(pattern)
     ret = Multiset.new
     @entries.each_pair do |item, count|
@@ -939,20 +979,20 @@ class Multiset
     ret
   end
   
+  # Three elements are given to the block for each (non-duplicated) items in <code>self</code>:
+  # the last result of the block, the item, and its number in <code>self</code>.
+  # As for the first block call, the first argument is <code>init</code>.
+  # The result of the last block call is returned.
+  # 
+  # Different from Enumerable#inject, <code>init</code> cannot be omitted.
+  # In addition, Symbol cannot be given instead of a block.
+  # 
   # ブロックに「1回前のブロック呼び出しの返り値」「<code>self</code>の要素」「その個数」の
   # 3つ組を順次与え、最後にブロックを呼んだ結果を返します。ただし「1回前のブロック呼び出しの返り値」は、
   # 1回目のブロック呼び出しの際については、代わりに<code>init</code>の値が与えられます。
   # 
   # Enumerable#injectと異なり、<code>init</code>は省略できません。
   # またブロックの代わりにSymbolを与えることもできません。
-  # 
-  # Three elements are given to the block for each (non-duplicate) items:
-  # the last result of the block, the item and its count.
-  # As for the first block call, the first argument is <code>init</code>.
-  # The result of the last block call is returned.
-  # 
-  # Different from Enumerable#inject, <code>init</code> cannot be omitted.
-  # In addition, Symbol cannot be given instead of a block.
   def inject_with(init)
     @entries.each_pair do |item, count|
       init = yield(init, item, count)
@@ -960,113 +1000,128 @@ class Multiset
     init
   end
   
+  # Returns the largest item in <code>self</code>,
+  # or <code>nil</code> if no item is stored in <code>self</code>.
+  # If a block is given, they are ordered by giving pairs of items to the block.
+  # 
   # 最大の要素を返します。
   # 要素が存在しない場合はnilを返します。
   # ブロックが与えられた場合は、要素間の大小判定を、ブロックに2つの要素を与えることで行います。
-  # 
-  # Returns the largest item, or <code>nil</code> if no item is stored in <code>self</code>.
-  # If a block is given, their order is judged by giving two items to the block.
   def max(&block) # :yields: a, b
     @entries.keys.max(&block)
   end
   
+  # Returns the smallest item in <code>self</code>,
+  # or <code>nil</code> if no item is stored in <code>self</code>.
+  # If a block is given, they are ordered by giving pairs of items to the block.
+  # 
   # 最小の要素を返します。
   # 要素が存在しない場合はnilを返します。
   # ブロックが与えられた場合は、要素間の大小判定を、ブロックに2つの要素を与えることで行います。
-  # 
-  # Returns the smallest item, or <code>nil</code> if no item is stored in <code>self</code>.
-  # If a block is given, their order is judged by giving two items to the block.
   def min(&block) # :yields: a, b
     @entries.keys.min(&block)
   end
   
+  # Returns the pair consisting of the smallest and the largest item in <code>self</code>,
+  # or <code>nil</code> if no item is stored in <code>self</code>.
+  # If a block is given, they are ordered by giving pairs of items to the block.
+  # 
   # 最小の要素と最大の要素の組を返します。
   # ブロックが与えられた場合は、要素間の大小判定を、ブロックに2つの要素を与えることで行います。
-  # 
-  # Returns the pair consisting of the smallest and the largest item.
-  # If a block is given, their order is judged by giving two items to the block.
   def minmax(&block) # :yields: a, b
     @entries.keys.minmax(&block)
   end
   
+  # Returns the largest item by comparing the items in <code>self</code>
+  # by the results of the block.
+  # If no item is stored in <code>self</code>, <code>nil</code> is returned.
+  # 
   # ブロックの値を評価した結果が最大になるような要素を返します。
   # 要素が存在しない場合はnilを返します。
-  # 
-  # Returns the largest item, or <code>nil</code> if no item is stored in <code>self</code>.
   def max_by(&block) # :yields: item
     @entries.keys.max_by(&block)
   end
   
+  # Returns the largest item by comparing the items in <code>self</code>
+  # by the results of the block.
+  # If no item is stored in <code>self</code>, <code>nil</code> is returned.
+  #
   # ブロックの値を評価した結果が最小になるような要素を返します。
   # 要素が存在しない場合はnilを返します。
-  # 
-  # Returns the smallest item, or <code>nil</code> if no item is stored in <code>self</code>.
   def min_by(&block) # :yields: item
     @entries.keys.min_by(&block)
   end
   
+  # Returns the pair consisting of the smallest and the largest items  in <code>self</code>
+  # by comparing the items by the results of the block.
+  # If no item is stored in <code>self</code>, <code>nil</code> is returned.
+  #
   # ブロックの値を評価した結果が最小になる要素と最大になる要素の組を返します。
   # 要素が存在しない場合はnilを返します。
-  # 
-  # Returns the pair consisting of the smallest and the largest item.
   def minmax_by(&block) # :yields: item
     @entries.keys.minmax_by(&block)
   end
   
+  # Same as Multiset#max except that the following four:
+  # "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
+  #
   # Multiset#max と同様ですが、ブロックには「要素1」「要素1の出現数」「要素2」「要素2の出現数」の
   # 4引数が与えられます。
-  # 
-  # Same as Multiset#max, but four arguments: "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
   def max_with # :yields: item1, count1, item2, count2
     tmp = @entries.each_pair.max{ |a, b| yield(a[0], a[1], b[0], b[1]) }
     tmp ? tmp[0] : nil
   end
   
+  # Same as Multiset#min except that the following four:
+  # "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
+  #
   # Multiset#min と同様ですが、ブロックには「要素1」「要素1の出現数」「要素2」「要素2の出現数」の
   # 4引数が与えられます。
-  # 
-  # Same as Multiset#min, but four arguments: "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
   def min_with # :yields: item1, count1, item2, count2
     tmp = @entries.each_pair.min{ |a, b| yield(a[0], a[1], b[0], b[1]) }
     tmp ? tmp[0] : nil
   end
   
+  # Same as Multiset#minmax except that the following four:
+  # "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
+  #
   # Multiset#minmax と同様ですが、ブロックには「要素1」「要素1の出現数」「要素2」「要素2の出現数」の
   # 4引数が与えられます。
-  # 
-  # Same as Multiset#minmax, but four arguments: "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
   def minmax_with # :yields: item1, count1, item2, count2
     tmp = @entries.each_pair.minmax{ |a, b| yield(a[0], a[1], b[0], b[1]) }
     tmp ? [tmp[0][0], tmp[1][0]] : nil
   end
   
+  # Same as Multiset#max_by except that pairs of (non-duplicated) items and their counts
+  # are given to the block.
+  #
   # Multiset#max_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
-  # 
-  # Same as Multiset#min, but pairs of (non-duplicated) items and their counts are given to the block.
   def max_by_with(&block) # :yields: item, count
     tmp = @entries.each_pair.max_by(&block)
     tmp ? tmp[0] : nil # if @entries is not empty, tmp must be a two-element array
   end
   
-  # Multiset#min_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
-  # 
-  # Same as Multiset#max, but pairs of (non-duplicated) items and their counts are given to the block.
+  # Same as Multiset#min_by except that pairs of (non-duplicated) items and their counts
+  # are given to the block.
+  #
+  # Multiset#max_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
   def min_by_with(&block) # :yields: item, count
     tmp = @entries.each_pair.min_by(&block)
     tmp ? tmp[0] : nil # if @entries is not empty, tmp must be a two-element array
   end
   
+  # Same as Multiset#minmax_by except that pairs of (non-duplicated) items and their counts
+  # are given to the block.
+  #
   # Multiset#minmax_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
-  # 
-  # Same as Multiset#minmax, but pairs of (non-duplicated) items and their counts are given to the block.
   def minmax_by_with(&block) # :yields: item, count
     tmp = @entries.each_pair.minmax_by(&block)
     tmp[0] ? [tmp[0][0], tmp[1][0]] : nil
   end
   
-  # <code>self</code>の要素を並び替えた配列を生成します。
-  # 
   # Generates an array by sorting the items in <code>self</code>.
+  # 
+  # <code>self</code>の要素を並び替えた配列を生成します。
   def sort(&block) # :yields: a, b
     ret = []
     @entries.keys.sort(&block).each do |item|
@@ -1075,9 +1130,10 @@ class Multiset
     ret
   end
   
-  # Multiset#sortと同様ですが、ブロックには1つの要素が与えられ、その値が小さいものから順に並びます。
+  # The same as Multiset#sort except that, after giving the items to the block,
+  # the items are sorted by the values from the block.
   # 
-  # Same as Multiset#sort, but only one item is given to the block.
+  # Multiset#sortと同様ですが、ブロックには1つの要素が与えられ、その値が小さいものから順に並びます。
   def sort_by(&block) # :yields: item
     ret = []
     @entries.keys.sort_by(&block).each do |item|
@@ -1086,10 +1142,11 @@ class Multiset
     ret
   end
 
+  # Same as Multiset#sort except that the following four:
+  # "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
+  #
   # Multiset#sort と同様ですが、ブロックには「要素1」「要素1の出現数」「要素2」「要素2の出現数」の
   # 4引数が与えられます。
-  # 
-  # Same as Multiset#sort, but four arguments: "item 1", "number of item 1", "item 2" and "number of item 2" are given to the block.
   def sort_with # :yields: item1, count1, item2, count2
     ret = []
     @entries.each_pair.sort{ |a, b| yield(a[0], a[1], b[0], b[1]) }.each do |item_count|
@@ -1098,9 +1155,10 @@ class Multiset
     ret
   end
 
-  # Multiset#sort_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
+  # Same as Multiset#sort_by except that the pairs of (non-duplicated) items
+  # and their counts are given to the block.
   # 
-  # Same as Multiset#sort_by, but pairs of (non-duplicated) items and their counts are given to the block.
+  # Multiset#sort_by と同様ですが、ブロックには要素（重複なし）とその出現数の組が与えられます。
   def sort_by_with # :yields: item1, count1, item2, count2
     ret = []
     @entries.each_pair.sort_by{ |a| yield(*a) }.each do |item_count|
@@ -1111,16 +1169,16 @@ class Multiset
 end
 
 class Hash
-  # <code>self</code>を多重集合に変換し、その結果を返します。
-  # キーを要素、キーに対応する値をその要素の要素数とします。
+  # Generates multiset from <code>self</code>.
+  # Keys of the Hash are treated as items in the multiset,
+  # while values of the Hash are number of items.
   # 
-  # （例）<code>{:a => 4, :b => 2}.to_multiset # :aを4個、:bを2個含む多重集合</code>
+  # (example) <code>{:a => 4, :b => 2}.to_multiset # Multiset with four :a's and two :b's</code>
   # 
-  # Generates multiset from <code>self</code>.
-  # Keys are treated as elements, and values are number of elements
-  # in the multiset. For example,
+  # <code>self</code>を多重集合に変換し、その結果を返します。
+  # Hashのキーを要素、Hashの値をその要素の要素数とします。
   # 
-  # <code>{:a => 4, :b => 2}.to_multiset # Multiset with four :a's and two :b's</code>
+  # （例）<code>{:a => 4, :b => 2}.to_multiset # :aを4個、:bを2個含む多重集合</code>
   def to_multiset
     ret = Multiset.new
     self.each_pair{ |item, count| ret.renew_count(item, count) }