prawn 2.4.0 → 2.5.0

data/lib/prawn/document/column_box.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 
-# column_box.rb: Extends BoundingBox to allow for columns of text
-#
-# Author Paul Ostazeski.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require_relative 'bounding_box'
 
 module Prawn
-  class Document
+  class Document # rubocop: disable Style/Documentation
     # @group Experimental API
 
     # A column box is a bounding box with the additional property that when
@@ -17,16 +11,26 @@ module Prawn
     # same page, and only flow to the next page when all the columns are
     # filled.
     #
-    # column_box accepts the same parameters as bounding_box, as well as the
-    # number of :columns and a :spacer (in points) between columns. If resetting
-    # the top margin is desired on a new page (e.g. to allow for initial page
-    # wide column titles) the option :reflow_margins => true can be set.
-    #
-    # Defaults are :columns = 3, :spacer = font_size, and
-    # :reflow_margins => false
-    #
-    # Under PDF::Writer, "spacer" was known as "gutter"
+    # `column_box` accepts the same parameters as {bounding_box}, as well as the
+    # number of `:columns` and a `:spacer` (in points) between columns. If
+    # resetting the top margin is desired on a new page (e.g. to allow for
+    # initial page wide column titles) the option `reflow_margins: true` can be
+    # set.
     #
+    # @overload column_box(point, options = {})
+    #   @param point [Array(Number, Number)]
+    #   @param options [Hash{Symbol => any}]
+    #   @option options :width [Number]
+    #     width of the new column box, must be specified.
+    #   @option options :height [Number]
+    #     height of the new column box, stretchy box if omitted.
+    #   @option options :hold_position [Boolean]
+    #     whether to put cursor at the bottom of the column box.
+    #   @option options :columns [Integer] (3)
+    #   @option options :spacer [Number] (font_size)
+    #   @option options :reflow_margins [Boolean] (false)
+    #   @yieldparam parent_box [BoundingBox] parent bounding box
+    #   @return [void]
     def column_box(*args, &block)
       init_column_box(block) do |parent_box|
         map_to_absolute!(args[0])
@@ -48,11 +52,20 @@ module Prawn
       @bounding_box = parent_box
     end
 
-    # Implements the necessary functionality to allow Document#column_box to
+    # Implements the necessary functionality to allow {Document#column_box} to
     # work.
     #
     class ColumnBox < BoundingBox
-      def initialize(document, parent, point, options = {}) #:nodoc:
+      # @param point [Array(Number, Number)]
+      # @param options [Hash{Symbol => any}]
+      # @option options :width [Number]
+      #   width of the new column box, must be specified.
+      # @option options :height [Number]
+      #   height of the new column box, stretchy box if omitted.
+      # @option options :columns [Integer] (3)
+      # @option options :spacer [Number] (font_size)
+      # @option options :reflow_margins [Boolean] (false)
+      def initialize(document, parent, point, options = {})
         super
         @columns = options[:columns] || 3
         @spacer = options[:spacer] || @document.font_size
@@ -60,39 +73,46 @@ module Prawn
         @reflow_margins = options[:reflow_margins]
       end
 
-      # The column width, not the width of the whole box,
-      # before left and/or right padding
+      # The column width, not the width of the whole box, before left and/or
+      # right padding.
+      #
+      # @return [Number]
       def bare_column_width
-        (@width - @spacer * (@columns - 1)) / @columns
+        (@width - (@spacer * (@columns - 1))) / @columns
       end
 
-      # The column width after padding.
-      # Used to calculate how long a line of text can be.
+      # The column width after padding. Used to calculate how long a line of
+      # text can be.
       #
+      # @return [Number]
       def width
         bare_column_width - (@total_left_padding + @total_right_padding)
       end
 
       # Column width including the spacer.
       #
+      # @return [Number]
       def width_of_column
         bare_column_width + @spacer
       end
 
-      # x coordinate of the left edge of the current column
+      # x coordinate of the left edge of the current column.
       #
+      # @return [Number]
       def left_side
         absolute_left + (width_of_column * @current_column)
       end
 
-      # Relative position of the left edge of the current column
+      # Relative position of the left edge of the current column.
       #
+      # @return [Number]
       def left
         width_of_column * @current_column
       end
 
-      # x co-orordinate of the right edge of the current column
+      # x coordinate of the right edge of the current column.
       #
+      # @return [Number]
       def right_side
         columns_from_right = @columns - (1 + @current_column)
         absolute_right - (width_of_column * columns_from_right)
@@ -100,12 +120,15 @@ module Prawn
 
       # Relative position of the right edge of the current column.
       #
+      # @return [Number]
       def right
         left + width
       end
 
       # Moves to the next column or starts a new page if currently positioned at
       # the rightmost column.
+      #
+      # @return [void]
       def move_past_bottom
         @current_column = (@current_column + 1) % @columns
         @document.y = @y
@@ -120,20 +143,32 @@ module Prawn
       # Override the padding functions so as not to split the padding amount
       # between all columns on the page.
 
+      # @private
+      # @param left_padding [Number]
+      # @return [void]
       def add_left_padding(left_padding)
         @total_left_padding += left_padding
         @x += left_padding
       end
 
+      # @private
+      # @param left_padding [Number]
+      # @return [void]
       def subtract_left_padding(left_padding)
         @total_left_padding -= left_padding
         @x -= left_padding
       end
 
+      # @private
+      # @param right_padding [Number]
+      # @return [void]
       def add_right_padding(right_padding)
         @total_right_padding += right_padding
       end
 
+      # @private
+      # @param right_padding [Number]
+      # @return [void]
       def subtract_right_padding(right_padding)
         @total_right_padding -= right_padding
       end

data/lib/prawn/document/internals.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-# internals.rb : Implements document internals for Prawn
-#
-# Copyright August 2008, Gregory Brown. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require 'forwardable'
 
 module Prawn
@@ -28,37 +22,52 @@ module Prawn
         on_page_create
       ] => :renderer
 
+      # Save current graphics state.
+      #
+      # @yield Restores graphic state after the block.
+      # @return [void]
       def save_graphics_state(state = nil, &block)
         save_transformation_stack
         renderer.save_graphics_state(state, &block)
+        restore_transformation_stack if block
       end
 
+      # Restore graphic state.
+      #
+      # @return [void]
       def restore_graphics_state
         restore_transformation_stack
         renderer.restore_graphics_state
       end
 
-      # FIXME: This is a circular reference, because in theory Prawn should
-      # be passing instances of renderer to PDF::Core::Page, but it's
-      # passing Prawn::Document objects instead.
+      # @devnote
+      #   FIXME: This is a circular reference, because in theory Prawn should be
+      #   passing instances of renderer to PDF::Core::Page, but it's passing
+      #   Prawn::Document objects instead.
       #
       # A proper design would probably not require Prawn to directly instantiate
       # PDF::Core::Page objects at all!
       delegate [:compression_enabled?] => :renderer
 
-      # FIXME: More circular references in PDF::Core::Page.
+      # @devnote
+      #   FIXME: More circular references in PDF::Core::Page.
       delegate %i[ref ref! deref] => :renderer
 
-      # FIXME: Another circular reference, because we mix in a module from
-      # PDF::Core to provide destinations, which in theory should not
-      # rely on a Prawn::Document object but is currently wired up that way.
+      # @devnote
+      #   FIXME: Another circular reference, because we mix in a module from
+      #   PDF::Core to provide destinations, which in theory should not rely on
+      #   a Prawn::Document object but is currently wired up that way.
       delegate [:names] => :renderer
 
-      # FIXME: Circular reference because we mix PDF::Core::Text into
-      # Prawn::Document. PDF::Core::Text should either be split up or
-      # moved in its entirety back up into Prawn.
+      # @devnote
+      #   FIXME: Circular reference because we mix PDF::Core::Text into
+      #   Prawn::Document. PDF::Core::Text should either be split up or moved in
+      #   its entirety back up into Prawn.
       delegate [:add_content] => :renderer
 
+      # Document renderer.
+      #
+      # @return [PDF::Core::Renderer]
       def renderer
         @renderer ||= PDF::Core::Renderer.new(state)
       end

data/lib/prawn/document/span.rb

@@ -7,27 +7,29 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 module Prawn
-  class Document
+  class Document # rubocop: disable Style/Documentation
     # @group Stable API
 
-    # A span is a special purpose bounding box that allows a column of
-    # elements to be positioned relative to the margin_box.
+    # A span is a special purpose bounding box that allows a column of elements
+    # to be positioned relative to the margin_box.
     #
-    # Arguments:
-    # +width+:: The width of the column in PDF points
+    # This method is typically used for flowing a column of text from one page
+    # to the next.
     #
-    # Options:
-    # <tt>:position</tt>:: One of :left, :center, :right or an x offset
-    #
-    # This method is typically used for flowing a column of text from one
-    # page to the next.
-    #
-    #  span(350, :position => :center) do
-    #    text "Here's some centered text in a 350 point column. " * 100
-    #  end
+    # @example
+    #   span(350, position: :center) do
+    #     text "Here's some centered text in a 350 point column. " * 100
+    #   end
     #
+    # @param width [Number] The width of the column in PDF points
+    # @param options [Hash{Symbol => any }]
+    # @option options :position [:left, :center, :right, Number]
+    #   position of the span relative to the page margins.
+    # @yield
+    # @return [void]
+    # @raise [ArgumentError] For unsupported `:position` value.
     def span(width, options = {})
-      Prawn.verify_options [:position], options
+      Prawn.verify_options([:position], options)
       original_position = y
 
       # FIXME: Any way to move this upstream?
@@ -36,7 +38,7 @@ module Prawn
         when :left
           margin_box.absolute_left
         when :center
-          margin_box.absolute_left + margin_box.width / 2.0 - width / 2.0
+          margin_box.absolute_left + (margin_box.width / 2.0) - (width / 2.0)
         when :right
           margin_box.absolute_right - width
         when Numeric
@@ -50,9 +52,9 @@ module Prawn
         bounding_box(
           [
             left_boundary,
-            margin_box.absolute_top
+            margin_box.absolute_top,
           ],
-          width: width
+          width: width,
         ) do
           self.y = original_position
           yield