Update documentation

lib/rex/java/serialization/model/annotation.rb

@@ -12,6 +12,7 @@ module Rex
           #   @return [Array] The annotation contents
           attr_accessor :contents
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.contents = []

lib/rex/java/serialization/model/block_data.rb

@@ -12,6 +12,7 @@ module Rex
           #   @return [String] the contents of the block
           attr_accessor :contents
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           # @param contents [String] the contents of the block
           def initialize(stream = nil, contents = '')
             super(stream)

lib/rex/java/serialization/model/block_data_long.rb

@@ -12,6 +12,7 @@ module Rex
           #   @return [String] the contents of the block
           attr_accessor :contents
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           # @param contents [String] the contents of the block
           def initialize(stream = nil, contents = '')
             super(stream)

lib/rex/java/serialization/model/class_desc.rb

@@ -9,6 +9,7 @@ module Rex
 
           attr_accessor :description
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.description = nil

lib/rex/java/serialization/model/element.rb

@@ -16,6 +16,7 @@ module Rex
             elem.decode(io)
           end
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             self.stream = stream
           end

lib/rex/java/serialization/model/field.rb

@@ -18,6 +18,7 @@ module Rex
           #   @return [Java::Serialization::Model::Utf] The type of the field on object types.
           attr_accessor :field_type
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.type = ''

lib/rex/java/serialization/model/new_array.rb

@@ -17,6 +17,7 @@ module Rex
           #   @return [Array] The contents of the java array
           attr_accessor :values
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.array_description = nil

lib/rex/java/serialization/model/new_class_desc.rb

@@ -26,6 +26,7 @@ module Rex
           #   @return [Java::Serialization::Model::ClassDesc] The java class superclass description
           attr_accessor :super_class
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.class_name = nil

lib/rex/java/serialization/model/new_enum.rb

@@ -14,6 +14,7 @@ module Rex
           #   @return [Array] The constant value in the Java Enum
           attr_accessor :constant_name
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.enum_description = nil

lib/rex/java/serialization/model/new_object.rb

@@ -14,6 +14,7 @@ module Rex
           #   @return [Array] The data of the object
           attr_accessor :class_data
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
             self.class_desc = nil
@@ -32,7 +33,7 @@ module Rex
             if class_desc.description.class == Rex::Java::Serialization::Model::NewClassDesc
               self.class_data = decode_class_data(io, class_desc.description)
             elsif class_desc.description.class == Rex::Java::Serialization::Model::Reference
-              ref = class_desc.description.handler - BASE_WIRE_HANDLE
+              ref = class_desc.description.handle - BASE_WIRE_HANDLE
               self.class_data = decode_class_data(io, stream.references[ref])
             end
 

lib/rex/java/serialization/model/reference.rb

@@ -2,33 +2,46 @@ module Rex
   module Java
     module Serialization
       module Model
+        # This class provides a Java Reference representation.
         class Reference < Element
 
-          attr_accessor :handler
+          # @!attribute contents
+          #   @return [Fixnum] The stream handle being referenced
+          attr_accessor :handle
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           def initialize(stream = nil)
             super(stream)
-            self.handler = 0
+            self.handle = 0
           end
 
+          # Deserializes a Java::Serialization::Model::Reference
+          #
+          # @param io [IO] the io to read from
+          # @return [self] if deserialization succeeds
+          # @raise [RuntimeError] if deserialization doesn't succeed
           def decode(io)
-            handler_raw = io.read(4)
-            unless handler_raw && handler_raw.length == 4
+            handle_raw = io.read(4)
+            unless handle_raw && handle_raw.length == 4
               raise ::RuntimeError, 'Failed to unserialize Reference'
             end
 
-            self.handler = handler_raw.unpack('N')[0]
+            self.handle = handle_raw.unpack('N')[0]
 
             self
           end
 
+          # Serializes the Java::Serialization::Model::Reference
+          #
+          # @return [String] if serialization succeeds
+          # @raise [RuntimeError] if serialization doesn't succeed
           def encode
-            if handler < BASE_WIRE_HANDLE
+            if handle < BASE_WIRE_HANDLE
               raise ::RuntimeError, 'Failed to serialize Reference'
             end
 
             encoded = ''
-            encoded << [handler].pack('N')
+            encoded << [handle].pack('N')
 
             encoded
           end

lib/rex/java/serialization/model/stream.rb

@@ -14,22 +14,20 @@ module Rex
           #   @return [Fixnum] The stream version
           attr_accessor :version
           # @!attribute contents
-          #   @return [Array] The stream's contents
+          #   @return [Array] The stream contents
           attr_accessor :contents
+          # @!attribute references
+          #   @return [Array] The stream objects to be referenced through handles
           attr_accessor :references
 
           def initialize(stream = nil)
-            super(stream)
+            super(nil)
             self.magic = STREAM_MAGIC
             self.version = STREAM_VERSION
             self.contents = []
             self.references = []
           end
 
-          def add_reference(ref)
-            self.references.push(ref)
-          end
-
           # Deserializes a Java::Serialization::Model::Stream
           #
           # @param io [IO] the io to read from
@@ -61,6 +59,13 @@ module Rex
             encoded
           end
 
+          # Adds an element to the references array
+          #
+          # @param io [Rex::Java::Serialization::Model::Element] the object to save as reference dst
+          def add_reference(ref)
+            self.references.push(ref)
+          end
+
           private
 
           # Deserializes the magic stream value

lib/rex/java/serialization/model/utf.rb

@@ -12,6 +12,7 @@ module Rex
           #   @return [String] the contents of the string
           attr_accessor :contents
 
+          # @param stream [Rex::Java::Serialization::Model::Stream] the stream where it belongs to
           # @param contents [String] the contents of the utf string
           def initialize(stream = nil, contents = '')
             super(stream)

spec/lib/rex/java/serialization/model/stream_spec.rb

@@ -70,6 +70,10 @@ describe Rex::Java::Serialization::Model::Stream do
       expect(stream.version).to eq(Rex::Java::Serialization::STREAM_VERSION)
     end
 
+    it "initializes references as empty array " do
+      expect(stream.references).to be_empty
+    end
+
     it "initializes stream to nil by default" do
       expect(stream.stream).to be_nil
     end