Merge pull request #2539 from universato/refine-gem__version

Gem::Versionのメソッドの説明やコードを加筆

refm/api/src/rubygems/version/Gem__Version

@@ -36,66 +36,134 @@ p versions.sort_by{ |v| Gem::Version.new(v) }
 
 == Singleton Methods
 
+#@since 2.5.0
 --- correct?(version) -> bool
 
-version が正しいバージョンであれば真を返します。そうでなければ偽を返します。
+version が正しいバージョンであれば true を返します。そうでなければ false を返します。
+
+#@samplecode
+p Gem::Version.correct?("9.1")       # => true
+p Gem::Version.correct?("incorrect") # => false
+
+p Gem::Version.correct?(nil)         # => true
+# nil versions are discouraged and will be deprecated in Rubygems 4
+# version が nil のときは true を返しますが、推奨はされず、Ruby 2.6以降では警告がでます。
+#@end
+#@else
+--- correct?(version) -> 0 | nil
+
+version が正しいバージョンであれば 0 を返します。そうでなければ nil を返します。
+
+#@samplecode
+p Gem::Version.correct?("9.1")       # => 0
+p Gem::Version.correct?("incorrect") # => nil
+
+p Gem::Version.correct?(nil)         # => 0
+#@end
+#@end
 
 @param version バージョンを文字列か数値で指定します。
 
+
 --- create(input) -> Gem::Version | nil
 
 [[c:Gem::Version]] のインスタンスを作成するためのファクトリメソッドです。
 
-例:
-
-  ver1 = Gem::Version.create('1.3.17')   # => #<Gem::Version "1.3.17">
-  ver2 = Gem::Version.create(ver1)       # => #<Gem::Version "1.3.17">
-  ver3 = Gem::Version.create(nil)        # => nil
+#@samplecode
+ver1 = Gem::Version.create('1.3.17')   # => #<Gem::Version "1.3.17">
+ver2 = Gem::Version.create(ver1)       # => #<Gem::Version "1.3.17">
+ver3 = Gem::Version.create(nil)        # => nil
+#@end
 
 @param input [[c:Gem::Version]] のインスタンスか文字列を指定します。
 
 @raise ArgumentError input がバージョンとして不正なオブジェクトである場合に発生します。
 
 @see [[m:Gem::Version.correct?]]
 
+
+--- new(version) -> Gem::Version
+
+バージョンを表す文字列から、Gem::Version インスタンスを作成します。
+
+引数のバージョンを表す文字列とは、 数字かASCII文字の連続であり、ドットで区切られたものです。
+
+#@samplecode
+p Gem::Version.new('1.2.0a') # => #<Gem::Version "1.2.0a">
+
+# Ruby 2.4.1より、空白文字以外の文字がない場合、バージョンは "0" になります。
+p Gem::Version.new(' ') #=> #<Gem::Version "0">
+#@end
+
+@param version
+@raise ArgumentError input がバージョンとして不正なオブジェクトである場合に発生します。
+                     これは Gem::Version.correct? により、判定されます。
+
+
 == Public Instance Methods
 
---- <=>(other) -> Integer | nil
+--- <=>(other) -> -1 | 0 | 1 | nil
 
-self と other を比較して、self が大きい時に 1 
-等しい時に 0、小さい時に -1 の整数を返します。
+self と other を比較して、self が小さい時に -1、
+等しい時に 0、大きい時に 1 の整数を返します。
+また、other が Gem::Version ではなく比較できないとき、 nil を返します。
+
+#@samplecode
+p Gem::Version.new("3.9.0") <=>  Gem::Version.new("3.10.0") # => -1
+p Gem::Version.new("3.0.0") <=>  Gem::Version.new("3.0.0")  # =>  0
+p Gem::Version.new("3.0.0") <=>  Gem::Version.new("3.0")    # =>  0
+
+p Gem::Version.new("3.9.0") <=> "3.9.0" # => nil
+#@end
 
 @param other 比較対象の [[c:Gem::Version]] のインスタンスを指定します。
 
 --- bump -> Gem::Version
 
 最後の一桁を切り上げた新しい [[c:Gem::Version]] のインスタンスを返します。
 
-例:
+ただし、英字のプレリリースの部分は、無視されます。
 
-  ver1 = Gem::Version.create('5.3.1') # => #<Gem::Version "5.3.1">
-  ver2 = ver1.bump                    # => #<Gem::Version "5.4">
+#@samplecode
+p Gem::Version.new('5.3.1').bump     # => #<Gem::Version "5.4">
+p Gem::Version.new('5.3.1.a.1').bump # => #<Gem::Version "5.4">
+p Gem::Version.new('5.3.1.3.1').bump # => #<Gem::Version "5.3.1.4">
+#@end
 
 --- eql?(other) -> bool
 
-self と other の [[m:Gem::Version#version]] が等しいとき真を返します。
-そうでなければ偽を返します。
+self と other の [[m:Gem::Version#version]] のバージョンが等しいとき true を返します。
+そうでなければ false を返します。
+
+Comparable を include して作られた == と異なり、"1.0" と "1" は異なるものと判定します。
 
-例:
+#@samplecode
+ver0 = Gem::Version.create('1.0')   # #<Gem::Version "1.0">
+ver1 = Gem::Version.create('1.0')   # #<Gem::Version "1.0">
+ver2 = Gem::Version.create('1')     # #<Gem::Version "1">
 
-  ver1 = Gem::Version.create('1.0')   # => #<Gem::Version "1.0">
-  ver2 = Gem::Version.create('1')     # => #<Gem::Version "1">
-  ver3 = Gem::Version.create('1.2.3') # => #<Gem::Version "1.2.3">
-  ver1.eql?(ver2)                     # => true
-  ver1.eql?(ver3)                     # => false
+p ver0.eql?(ver1)     # => true
+p ver1.eql?(ver2)     # => false
+p ver1 == ver2        # => true
+#@end
 
 --- marshal_dump -> Array
 
 完全なオブジェクトではなく、バージョン文字列のみダンプします。
 
---- marshal_load(array) -> String
+#@samplecode
+p Gem::Version.new('1.2.0a').marshal_dump  # => ["1.2.0a"]
+#@end
+
+--- marshal_load(array) -> nil
 
-ダンプされた情報をロードします。
+ダンプされた情報をロードし、自身を破壊的に変更します。
+
+#@samplecode
+version = Gem::Version.new('')
+version.marshal_load(["1.2.0a"])
+p version # => #<Gem::Version "1.2.0a">
+#@end
 
 @param array バージョン情報を含む配列を指定します。
 
@@ -104,22 +172,31 @@ self と other の [[m:Gem::Version#version]] が等しいとき真を返しま
 #@#
 #@# :nodoc:
 
+#@#--- segments -> Array
+#@#
+#@# :nodoc:
+
+#@since 2.5.0
+#@#--- canonical_segments -> Array
+#@#
+#@# :nodoc:
+#@end
+
 --- version -> String
 --- to_s -> String
 
 バージョン情報を文字列として返します。
 
---- version=(version)
-
-self のバージョン情報を書き換えます。
+#@samplecode
+version = Gem::Version.new("1.2.3a")
+p version.to_s     # => "1.2.3a"
+p version.version  # => "1.2.3a"
+#@end
 
 #@#--- yaml_initialize(tag, values) -> String
 #@#
 #@# :nodoc:
 
-#@#--- Gem::Version::Requirement
-#@todo Gem::Requirement に書く
-
 --- prerelease? -> bool
 
 self がプレリリースと思われる文字を含むバージョンかどうかを返します。
@@ -146,6 +223,14 @@ Gem::Version.new('1.2.0').release  # => #<Gem::Version "1.2.0">
 
 == Constants
 
+--- Requirement -> Class
+
+[[c:Gem::Requirement]] のエイリアスです。
+
+#@samplecode
+p Gem::Version::Requirement == Gem::Requirement  # => true
+#@end
+
 #@#--- VERSION_PATTERN -> String
 #@#
 #@# :nodoc: