Add basic documentation to paginator methods

Author: tmaier

lib/pliny/helpers/paginator.rb

@@ -1,9 +1,28 @@
 module Pliny::Helpers
   module Paginator
+
+    # Sets the HTTP Range header for pagination if necessary
+    #
+    # @see uuid_paginator
+    # @see integer_paginator
+    # @see Pliny::Helpers::Paginator::Paginator
     def paginator(count, options = {}, &block)
       Paginator.run(self, count, options, &block)
     end
 
+    # paginator for UUID columns
+    #
+    # @example call in the Endpoint
+    #   articles = uuid_paginator(Article, args: { max: 10 })
+    #
+    # @example HTTP header returned
+    #   Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef/400; max=10
+    #   Next-Range: id 76543210-89ab-cdef-0123-456789abcdef..76543210-89ab-cdef-0123-456789abcdef/400; max=10
+    #
+    # @param [Object] resource the resource to paginate
+    # @param [Hash] options
+    # @return [Object] modified resource (by order, limit and offset)
+    # @see paginator
     def uuid_paginator(resource, options = {})
       paginator(resource.count, options) do |paginator|
         sort_by_conversion = { id: :uuid }
@@ -27,6 +46,21 @@ def uuid_paginator(resource, options = {})
       end
     end
 
+    # paginator for integer columns
+    #
+    # @example call in the Endpoint
+    #   paginator = integer_paginator(User.count)
+    #   users = User.order(paginator[:order_by]).limit(paginator[:limit]).offset(paginator[:offset])
+    #
+    # @example HTTP header returned
+    #   Content-Range: id 0..199/400; max=200
+    #   Next-Range: id 200..399/400; max=200
+    #
+    # @param [Integer] count the count of resources
+    # @param [Hash] options
+    # @return [Hash] with :order_by and calculated :offset and :limit
+    # @see paginator
+    # @see Pliny::Helpers::Paginator::IntegerPaginator
     def integer_paginator(count, options = {})
       IntegerPaginator.run(self, count, options)
     end

lib/pliny/helpers/paginator/paginator.rb

@@ -18,6 +18,18 @@ def run(*args, &block)
         end
       end
 
+      # Initializes an instance of Paginator
+      #
+      # @param [Sinatra::Base] the controller calling the paginator
+      # @param [Integer] count the count of resources
+      # @param [Hash] options for the paginator
+      # @option options [Array<Symbol>] :accepted_ranges ([:id]) fields allowed to sort the listing
+      # @option options [Symbol] :sort_by (:id) field to sort the listing
+      # @option options [String] :first ID or name of the first element of the current page
+      # @option options [String] :last ID or name of the last element of the current page
+      # @option options [String] :next_first ID or name of the first element of the next page
+      # @option options [String] :next_last ID or name of the last element of the next page
+      # @option options [Hash] :args ({max: 200}) arguments for the HTTP Range header
       def initialize(sinatra, count, options = {})
         @sinatra = sinatra
         @count   = count
@@ -34,6 +46,11 @@ def initialize(sinatra, count, options = {})
           .merge(options)
       end
 
+      # executes the paginator and sets the HTTP headers if necessary
+      #
+      # @yieldparam paginator [Paginator]
+      # @yieldreturn [Object]
+      # @return [Object] the result of the block yielded
       def run
         options.merge!(request_options)