updated documents

frsyuki · frsyuki · commit 3c15dad085f3 · 2012-09-23T16:53:35.000-07:00
diff --git a/doclib/msgpack/buffer.rb b/doclib/msgpack/buffer.rb
@@ -37,12 +37,19 @@ def empty?
     # Appends the given data to the buffer.
     #
     # @param data [String]
-    # @return [Buffer] self
+    # @return [Integer] byte size written
     #
-    def append(data)
+    def write(data)
     end
 
-    alias << append
+    #
+    # Appends the given data to the buffer.
+    #
+    # @param data [String]
+    # @return [Buffer] self
+    #
+    def <<(data)
+    end
 
     # Consumes _n_ bytes from the head of the buffer and returns consumed data.
     # If the size of the buffer is less than _n_, it reads all of data in the buffer.
@@ -87,7 +94,6 @@ def read_all
 
     #
     # Consumes _n_ bytes from the head of the buffer.
-    #
     # If the size of the buffer is less than _n_, it skips all of data in the buffer and returns integer less than _n_.
     #
     # If _n_ is 0, it does nothing and returns _0_.
diff --git a/doclib/msgpack/unpacker.rb b/doclib/msgpack/unpacker.rb
@@ -16,21 +16,25 @@ class Unpacker
     #   @param io [IO]
     #   @param options [Hash]
     #   This unpacker reads data from the _io_ to fill the internal buffer.
-    #   _io_ must respond to readpartial(length,string) or read(length,string) method.
+    #   _io_ must respond to readpartial(length[,string]) or read(length[,string]) method.
     #
     def initialize(*args)
     end
 
     #
     # Internal buffer
     #
-    # @return MessagePack::Unpacker
+    # @return [MessagePack::Unpacker]
     #
     attr_reader :buffer
 
     #
     # Deserializes an object from internal buffer and returns it.
     #
+    # If there're not enough buffer, this method raises EOFError.
+    # If data format is invalid, this method raises MessagePack::MalformedFormatError.
+    # If the stack is too deep, this method raises MessagePack::StackError.
+    #
     # @return [Object] deserialized object
     #
     def read
@@ -41,25 +45,31 @@ def read
     #
     # Deserializes an object and ignores it. This method is faster than _read_.
     #
+    # This method could raise same errors with _read_.
+    #
     # @return nil
     #
     def skip
     end
 
     #
     # Deserializes a nil value if it exists and returns _true_.
-    # Otherwise, if a byte exists but the byte is not nil value or the internal buffer is empty, returns _false_.
+    # Otherwise, if a byte exists but the byte doesn't represent nil value,
+    # returns _false_.
+    #
+    # If there're not enough buffer, this method raises EOFError.
     #
     # @return [Boolean]
     #
-    def skip
+    def skip_nil
     end
 
     #
     # Read a header of an array and returns its size.
     # It converts a serialized array into a stream of elements.
     #
     # If the serialized object is not an array, it raises MessagePack::TypeError.
+    # If there're not enough buffer, this method raises EOFError.
     #
     # @return [Integer] size of the array
     #
@@ -71,6 +81,7 @@ def read_array_header
     # It converts a serialized map into a stream of key-value pairs.
     #
     # If the serialized object is not a map, it raises MessagePack::TypeError.
+    # If there're not enough buffer, this method raises EOFError.
     #
     # @return [Integer] size of the map
     #
@@ -82,6 +93,7 @@ def read_map_header
     # This method calls buffer.append(data).
     #
     # @param data [String]
+    # @return [Unpacker] self
     #
     def feed(data)
     end
@@ -91,8 +103,10 @@ def feed(data)
     #
     # It repeats until the internal buffer does not include any complete objects.
     #
-    # If the internal IO was set, it reads data from the IO when the buffer becomes empty,
-    # and returns when the IO raised EOFError.
+    # If the an IO is set, it repeats to read data from the IO when the buffer
+    # becomes empty until the IO raises EOFError.
+    #
+    # This method could raise same errors with _read_ excepting EOFError.
     #
     # @yieldparam object [Object] deserialized object
     # @return nil
diff --git a/spec/buffer_spec.rb b/spec/buffer_spec.rb
@@ -180,11 +180,11 @@
     }
   end
 
-  it 'short append increments size' do
+  it 'short write increments size' do
     case_keys.each {|k|
       sz = examples[k].size
       10.times do |i|
-        cases[k].append 'short'
+        cases[k].write 'short'
         sz += 'short'.size
         cases[k].size.should == sz
       end
@@ -320,28 +320,28 @@
     }
   end
 
-  it 'big append and modify reference' do
+  it 'big write and modify reference' do
     big2 = "a" * (1024*1024 + 2)
 
     case_keys.each {|k|
       big1 = "a" * (1024*1024 + 2)
-      cases[k].append(big1)
+      cases[k].write(big1)
       big1 << 'x'
       cases[k].read.should == examples[k] + big2
     }
   end
 
-  it 'big append -> short append' do
+  it 'big write -> short write' do
     biglen = 1024*1024 + 2
     big1 = "a" * (1024*1024 + 2)
 
     case_keys.each {|k|
       sz = examples[k].size
 
-      cases[k].append big1
+      cases[k].write big1
       cases[k].size.should == sz + big1.size
 
-      cases[k].append("c")
+      cases[k].write("c")
       cases[k].size.should == sz + big1.size + 1
 
       cases[k].read_all.should == examples[k] + big1 + "c"
@@ -350,15 +350,15 @@
     }
   end
 
-  it 'big append 2'do
+  it 'big write 2'do
     big1 = "a" * (1024*1024 + 2)
     big2 = "b" * (1024*1024 + 2)
 
     case_keys.each {|k|
       sz = examples[k].size
 
-      cases[k].append big1
-      cases[k].append big2
+      cases[k].write big1
+      cases[k].write big2
       cases[k].size.should == sz + big1.size + big2.size
 
       cases[k].read_all(sz + big1.size).should == examples[k] + big1

Original file line number	Diff line number	Diff line change
`@@ -16,21 +16,25 @@ class Unpacker`
`16`	`16`	`# @param io [IO]`
`17`	`17`	`# @param options [Hash]`
`18`	`18`	`# This unpacker reads data from the _io_ to fill the internal buffer.`
`19`		`- # _io_ must respond to readpartial(length,string) or read(length,string) method.`
	`19`	`+ # _io_ must respond to readpartial(length[,string]) or read(length[,string]) method.`
`20`	`20`	`#`
`21`	`21`	`def initialize(*args)`
`22`	`22`	`end`
`23`	`23`
`24`	`24`	`#`
`25`	`25`	`# Internal buffer`
`26`	`26`	`#`
`27`		`- # @return MessagePack::Unpacker`
	`27`	`+ # @return [MessagePack::Unpacker]`
`28`	`28`	`#`
`29`	`29`	`attr_reader :buffer`
`30`	`30`
`31`	`31`	`#`
`32`	`32`	`# Deserializes an object from internal buffer and returns it.`
`33`	`33`	`#`
	`34`	`+ # If there're not enough buffer, this method raises EOFError.`
	`35`	`+ # If data format is invalid, this method raises MessagePack::MalformedFormatError.`
	`36`	`+ # If the stack is too deep, this method raises MessagePack::StackError.`
	`37`	`+ #`
`34`	`38`	`# @return [Object] deserialized object`
`35`	`39`	`#`
`36`	`40`	`def read`
`@@ -41,25 +45,31 @@ def read`
`41`	`45`	`#`
`42`	`46`	`# Deserializes an object and ignores it. This method is faster than _read_.`
`43`	`47`	`#`
	`48`	`+ # This method could raise same errors with _read_.`
	`49`	`+ #`
`44`	`50`	`# @return nil`
`45`	`51`	`#`
`46`	`52`	`def skip`
`47`	`53`	`end`
`48`	`54`
`49`	`55`	`#`
`50`	`56`	`# Deserializes a nil value if it exists and returns _true_.`
`51`		`- # Otherwise, if a byte exists but the byte is not nil value or the internal buffer is empty, returns _false_.`
	`57`	`+ # Otherwise, if a byte exists but the byte doesn't represent nil value,`
	`58`	`+ # returns _false_.`
	`59`	`+ #`
	`60`	`+ # If there're not enough buffer, this method raises EOFError.`
`52`	`61`	`#`
`53`	`62`	`# @return [Boolean]`
`54`	`63`	`#`
`55`		`- def skip`
	`64`	`+ def skip_nil`
`56`	`65`	`end`
`57`	`66`
`58`	`67`	`#`
`59`	`68`	`# Read a header of an array and returns its size.`
`60`	`69`	`# It converts a serialized array into a stream of elements.`
`61`	`70`	`#`
`62`	`71`	`# If the serialized object is not an array, it raises MessagePack::TypeError.`
	`72`	`+ # If there're not enough buffer, this method raises EOFError.`
`63`	`73`	`#`
`64`	`74`	`# @return [Integer] size of the array`
`65`	`75`	`#`
`@@ -71,6 +81,7 @@ def read_array_header`
`71`	`81`	`# It converts a serialized map into a stream of key-value pairs.`
`72`	`82`	`#`
`73`	`83`	`# If the serialized object is not a map, it raises MessagePack::TypeError.`
	`84`	`+ # If there're not enough buffer, this method raises EOFError.`
`74`	`85`	`#`
`75`	`86`	`# @return [Integer] size of the map`
`76`	`87`	`#`
`@@ -82,6 +93,7 @@ def read_map_header`
`82`	`93`	`# This method calls buffer.append(data).`
`83`	`94`	`#`
`84`	`95`	`# @param data [String]`
	`96`	`+ # @return [Unpacker] self`
`85`	`97`	`#`
`86`	`98`	`def feed(data)`
`87`	`99`	`end`
`@@ -91,8 +103,10 @@ def feed(data)`
`91`	`103`	`#`
`92`	`104`	`# It repeats until the internal buffer does not include any complete objects.`
`93`	`105`	`#`
`94`		`- # If the internal IO was set, it reads data from the IO when the buffer becomes empty,`
`95`		`- # and returns when the IO raised EOFError.`
	`106`	`+ # If the an IO is set, it repeats to read data from the IO when the buffer`
	`107`	`+ # becomes empty until the IO raises EOFError.`
	`108`	`+ #`
	`109`	`+ # This method could raise same errors with _read_ excepting EOFError.`
`96`	`110`	`#`
`97`	`111`	`# @yieldparam object [Object] deserialized object`
`98`	`112`	`# @return nil`