Document RubyES::Specification

Issue: #352

[ci skip]

Author: paneq

ruby_event_store/lib/ruby_event_store/specification.rb

@@ -1,6 +1,12 @@
 module RubyEventStore
+
+  # Used for building and executing the query specification.
   class Specification
+    # @private
+    # @api private
     NO_LIMIT = Object.new.freeze
+    # @private
+    # @api private
     NO_BATCH = Object.new.freeze
     DEFAULT_BATCH_SIZE = 100
 
@@ -35,18 +41,34 @@ def batched?
     end
     private_constant :Result
 
+    # @api private
+    # @private
     attr_reader :result
 
+    # @api private
+    # @private
     def initialize(repository, mapper, result = Result.new(:forward, :head, NO_LIMIT, Stream.new(GLOBAL_STREAM), NO_BATCH))
       @mapper = mapper
       @repository  = repository
       @result = result
     end
 
+    # Limits the query to certain stream.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @param stream_name [String] name of the stream to get events from
+    # @return [Specification]
     def stream(stream_name)
       Specification.new(repository, mapper, result.dup.tap { |r| r.stream = Stream.new(stream_name) })
     end
 
+    # Limits the query to events before or after another event.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @param start [:head, String] id of event to start reading from.
+    #   :head can mean the beginning or end of the stream, depending on the
+    #   #direction
+    # @return [Specification]
     def from(start)
       case start
       when Symbol
@@ -58,19 +80,38 @@ def from(start)
       Specification.new(repository, mapper, result.dup.tap { |r| r.start = start })
     end
 
+    # Sets the order of reading events to ascending (forward from the start).
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @return [Specification]
     def forward
       Specification.new(repository, mapper, result.dup.tap { |r| r.direction = :forward })
     end
 
+    # Sets the order of reading events to descending (backward from the start).
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @return [Specification]
     def backward
       Specification.new(repository, mapper, result.dup.tap { |r| r.direction = :backward })
     end
 
+    # Limits the query to specified number of events.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @param count [Integer] maximal number of events to retrieve
+    # @return [Specification]
     def limit(count)
       raise InvalidPageSize unless count && count > 0
       Specification.new(repository, mapper, result.dup.tap { |r| r.count = count })
     end
 
+    # Executes the query based on the specification built up to this point.
+    # Yields each batch of records that was retrieved from the store.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @yield [Array<Event, Proto>] batch of events
+    # @return [Enumerator, nil] Enumerator is returned when block not given
     def each_batch
       return to_enum(:each_batch) unless block_given?
 
@@ -80,6 +121,12 @@ def each_batch
       end
     end
 
+    # Executes the query based on the specification built up to this point.
+    # Yields events read from the store if block given. Otherwise, returns enumerable collection.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # @yield [Event, Proto] event
+    # @return [Enumerator, nil] Enumerator is returned when block not given
     def each
       return to_enum unless block_given?
 
@@ -88,6 +135,19 @@ def each
       end
     end
 
+    # Specifies that events should be obtained in batches.
+    # {http://railseventstore.org/docs/read/ Find out more}.
+    #
+    # Looping through a collection of events from the store
+    # can be inefficient since it will try to instantiate all
+    # the events at once.
+    #
+    # In that case, batch processing methods allow you to work
+    # with the records in batches, thereby greatly reducing
+    # memory consumption.
+    #
+    # @param batch_size [Integer] number of events to read in a single batch
+    # @return [Specification]
     def in_batches(batch_size = DEFAULT_BATCH_SIZE)
       Specification.new(repository, mapper, result.dup.tap { |r| r.batch_size = batch_size })
     end