prawn 2.4.0 → 2.5.0

data/lib/prawn/outline.rb

@@ -1,33 +1,33 @@
 # frozen_string_literal: true
 
 module Prawn
-  class Document
+  class Document # rubocop: disable Style/Documentation
     # @group Stable API
 
     # Lazily instantiates a Prawn::Outline object for document. This is used as
     # point of entry to methods to build the outline tree for a document's table
     # of contents.
+    #
+    # @return [Prawn::Outline]
     def outline
       @outline ||= Outline.new(self)
     end
   end
 
-  # The Outline class organizes the outline tree items for the document.
-  # Note that the prev and parent instance variables are adjusted while
-  # navigating through the nested blocks. These variables along with the
-  # presence or absense of blocks are the primary means by which the relations
-  # for the various OutlineItems and the OutlineRoot are set. Unfortunately, the
-  # best way to understand how this works is to follow the method calls through
-  # a real example.
-  #
-  # Some ideas for the organization of this class were gleaned from name_tree.
-  # In particular the way in which the OutlineItems are finally rendered into
-  # document objects in PdfObject through a hash.
+  # The Outline class organizes the outline tree items for the document. Note
+  # that the {prev} and {parent} are adjusted while navigating through the
+  # nested blocks. These attributes along with the presence or absence of blocks
+  # are the primary means by which the relations for the various
+  # `PDF::Core::OutlineItem`s and the `PDF::Core::OutlineRoot` are set.
   #
+  # Some ideas for the organization of this class were gleaned from `name_tree`.
+  # In particular the way in which the `PDF::Core::OutlineItem`s are finally
+  # rendered into document objects through a hash.
   class Outline
     # @private
     attr_accessor :parent, :prev, :document, :items
 
+    # @param document [Prawn::Document]
     def initialize(document)
       @document = document
       @parent = root
@@ -37,74 +37,81 @@ module Prawn
 
     # @group Stable API
 
-    # Returns the current page number of the document
+    # Returns the current page number of the document.
+    #
+    # @return [Integer]
     def page_number
       @document.page_number
     end
 
     # Defines/Updates an outline for the document.
+    #
     # The outline is an optional nested index that appears on the side of a PDF
     # document usually with direct links to pages. The outline DSL is defined by
-    # nested blocks involving two methods: section and page; see the
-    # documentation on those methods for their arguments and options. Note that
-    # one can also use outline#update to add more sections to the end of the
-    # outline tree using the same syntax and scope.
+    # nested blocks involving two methods: {section} and {page}. Note that one
+    # can also use {update} to add more sections to the end of the outline tree
+    # using the same syntax and scope.
     #
     # The syntax is best illustrated with an example:
     #
-    # Prawn::Document.generate(outlined_document.pdf) do
+    # ```ruby
+    # Prawn::Document.generate('outlined_document.pdf') do
     #   text "Page 1. This is the first Chapter. "
     #   start_new_page
     #   text "Page 2. More in the first Chapter. "
     #   start_new_page
     #   outline.define do
-    #     section 'Chapter 1', :destination => 1, :closed => true do
-    #       page :destination => 1, :title => 'Page 1'
-    #       page :destination => 2, :title => 'Page 2'
+    #     section 'Chapter 1', destination: 1, closed: true do
+    #       page destination: 1, title: 'Page 1'
+    #       page destination: 2, title: 'Page 2'
     #     end
     #   end
     #   start_new_page do
     #   outline.update do
-    #     section 'Chapter 2', :destination =>  2, do
-    #       page :destination => 3, :title => 'Page 3'
+    #     section 'Chapter 2', destination: 2, do
+    #       page destination: 3, title: 'Page 3'
     #     end
     #   end
     # end
+    # ```
     #
+    # @yield
+    # @return [void]
     def define(&block)
       instance_eval(&block) if block
     end
 
     alias update define
 
-    # Inserts an outline section to the outline tree (see outline#define).
-    # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method gives
-    # you the option to insert sections to the outline tree at any point during
-    # document generation. This method allows you to add a child subsection to
-    # any other item at any level in the outline tree.  Currently the only way
-    # to locate the place of entry is with the title for the item. If your title
-    # names are not unique consider using define_outline.
-    # The method takes the following arguments:
-    #   title: a string that must match an outline title to add
-    #     the subsection to
-    #   position: either :first or :last (the default) where the subsection will
-    #     be placed relative to other child elements. If you need to position
-    #     your subsection in between other elements then consider using
-    #     #insert_section_after
-    #   block: uses the same DSL syntax as outline#define, for example:
+    # Inserts an outline section to the outline tree (see {define}).
     #
-    # Consider using this method inside of outline.update if you want to have
-    # the outline object to be scoped as self (see #insert_section_after
-    # example).
+    # Although you will probably choose to exclusively use {define} so that your
+    # outline tree is contained and easy to manage, this method gives you the
+    # option to insert sections to the outline tree at any point during document
+    # generation. This method allows you to add a child subsection to any other
+    # item at any level in the outline tree. Currently the only way to locate
+    # the place of entry is with the title for the item. If your title names are
+    # not unique consider using {define}.
     #
-    #   go_to_page 2
-    #   start_new_page
-    #   text "Inserted Page"
-    #   outline.add_subsection_to :title => 'Page 2', :first do
-    #     outline.page :destination => page_number, :title => "Inserted Page"
-    #   end
+    # Consider using this method instead of {update} if you want to have the
+    # outline object to be scoped as self (see {insert_section_after} example).
     #
+    # ```ruby
+    # go_to_page 2
+    # start_new_page
+    # text "Inserted Page"
+    # outline.add_subsection_to title: 'Page 2', :first do
+    #   outline.page destination: page_number, title: "Inserted Page"
+    # end
+    # ```
+    #
+    # @param title [String] An outline title to add the subsection to.
+    # @param position [:first, :last] (:last)
+    #   Where the subsection will be placed relative to other child elements. If
+    #   you need to position your subsection in between other elements then
+    #   consider using {insert_section_after}.
+    # @yield Uses the same DSL syntax as {define}
+    # @return [void]
     def add_subsection_to(title, position = :last, &block)
       @parent = items[title]
       unless @parent
@@ -116,19 +123,18 @@ module Prawn
       insert_section(nxt, &block)
     end
 
-    # Inserts an outline section to the outline tree (see outline#define).
-    # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method gives
-    # you the option to insert sections to the outline tree at any point during
-    # document generation. Unlike outline.add_section, this method allows you to
-    # enter a section after any other item at any level in the outline tree.
+    # Inserts an outline section to the outline tree (see {define}).
+    #
+    # Although you will probably choose to exclusively use {define} so that your
+    # outline tree is contained and easy to manage, this method gives you the
+    # option to insert sections to the outline tree at any point during document
+    # generation. Unlike {add_subsection_to}, this method allows you to enter
+    # a section after any other item at any level in the outline tree.
     # Currently the only way to locate the place of entry is with the title for
     # the item. If your title names are not unique consider using
-    # define_outline.
-    # The method takes the following arguments:
-    #   title: the title of other section or page to insert new section after
-    #   block: uses the same DSL syntax as outline#define, for example:
+    # {define}.
     #
+    # @example
     #   go_to_page 2
     #   start_new_page
     #   text "Inserted Page"
@@ -138,6 +144,10 @@ module Prawn
     #     end
     #   end
     #
+    # @param title [String]
+    #   The title of other section or page to insert new section after.
+    # @yield Uses the same DSL syntax as {define}.
+    # @return [void]
     def insert_section_after(title, &block)
       @prev = items[title]
       unless @prev
@@ -149,67 +159,63 @@ module Prawn
       insert_section(nxt, &block)
     end
 
-    # See outline#define above for documentation on how this is used in that
-    # context
-    #
-    # Adds an outine section to the outline tree.
-    # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method gives
-    # you the option to add sections to the outline tree at any point during
-    # document generation. When not being called from within another #section
-    # block the section will be added at the top level after the other root
-    # elements of the outline.  For more flexible placement try using
-    # outline#insert_section_after and/or outline#add_subsection_to
+    # Adds an outline section to the outline tree.
     #
-    # Takes the following arguments:
-    #   title: the outline text that appears for the section.
-    #   options: destination - optional integer defining the page number for
-    #                 a destination link to the top of the page (using a :FIT
-    #                 destination).
-    #                 - or an array with a custom destination (see the #dest_*
-    #                 methods of the PDF::Destination module)
-    #            closed - whether the section should show its nested outline
-    #                     elements.
-    #                   - defaults to false.
-    #            block: more nested subsections and/or page blocks
+    # Although you will probably choose to exclusively use {define} so that your
+    # outline tree is contained and easy to manage, this method gives you the
+    # option to add sections to the outline tree at any point during document
+    # generation. When not being called from within another {section} block the
+    # section will be added at the top level after the other root elements of
+    # the outline. For more flexible placement try using {insert_section_after}
+    # and/or {add_subsection_to}.
     #
-    # example usage:
-    #
-    #   outline.section 'Added Section', :destination => 3 do
-    #     outline.page :destionation => 3, :title => 'Page 3'
+    # @example
+    #   outline.section 'Added Section', destination: 3 do
+    #     outline.page destionation: 3, title: 'Page 3'
     #   end
+    #
+    # @param title [String] The outline text that appears for the section.
+    # @param options [Hash{Symbol => any}]
+    # @option options :destination [Integer, Array]
+    #   - Optional page number for a destination link to the top of the page
+    #     (using a `:FIT` destination).
+    #   - An array with a custom destination (see the `#dest_*` methods of the
+    #     `PDF::Core::Destination` module).
+    # @option options :closed [Boolean] (false)
+    #   Whether the section should show its nested outline elements.
+    # @yield More nested subsections and/or page blocks.
+    # @return [void]
     def section(title, options = {}, &block)
       add_outline_item(title, options, &block)
     end
 
-    # See Outline#define above for more documentation on how it is used in that
-    # context
-    #
     # Adds a page to the outline.
-    # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method also
-    # gives you the option to add pages to the root of outline tree at any point
-    # during document generation. Note that the page will be added at the top
-    # level after the other root outline elements. For more flexible placement
-    # try using outline#insert_section_after and/or outline#add_subsection_to.
     #
-    # Takes the following arguments:
-    #   options:
-    #     title - REQUIRED. The outline text that appears for the page.
-    #     destination - optional integer defining the page number for
-    #             a destination link to the top of the page (using a :FIT
-    #             destination).
-    #             or an array with a custom destination (see the dest_* methods
-    #             of the PDF::Destination module)
-    #     closed - whether the section should show its nested outline elements.
-    #            - defaults to false.
-    # example usage:
+    # Although you will probably choose to exclusively use {define} so that your
+    # outline tree is contained and easy to manage, this method also gives you
+    # the option to add pages to the root of outline tree at any point during
+    # document generation. Note that the page will be added at the top level
+    # after the other root outline elements. For more flexible placement try
+    # using {insert_section_after} and/or {add_subsection_to}.
+    #
+    # @note This method is almost identical to {section} except that it does not
+    #   accept a block thereby defining the outline item as a leaf on the
+    #   outline tree structure.
     #
-    #   outline.page :title => "Very Last Page"
+    # @example
+    #   outline.page title: "Very Last Page"
     #
-    # Note: this method is almost identical to section except that it does not
-    # accept a block thereby defining the outline item as a leaf on the outline
-    # tree structure.
+    # @param options [Hash{Symbol => any}]
+    # @option options :title [String] REQUIRED.
+    #   The outline text that appears for the page.
+    # @option options :destination [Integer, Array]
+    #   - The page number for a destination link to the top of the page (using
+    #     a `:FIT` destination).
+    #   - An array with a custom destination (see the `#dest_*` methods of the
+    #     `PDF::Core::Destination` module).
+    # @option options :closed [Boolean] (false)
+    #   Whether the section should show its nested outline elements.
+    # @return [void]
     def page(options = {})
       if options[:title]
         title = options[:title]

data/lib/prawn/repeater.rb

@@ -1,19 +1,12 @@
 # frozen_string_literal: true
 
-# repeater.rb : Implements repeated page elements.
-# Heavy inspired by repeating_element() in PDF::Wrapper
-#   http://pdf-wrapper.rubyforge.org/
-#
-# Copyright November 2009, Gregory Brown. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 module Prawn
-  class Document
+  class Document # rubocop: disable Style/Documentation
     # A list of all repeaters in the document.
-    # See Document#repeat for details
+    # See {repeat} for details.
     #
     # @private
+    # @return [Array]
     def repeaters
       @repeaters ||= []
     end
@@ -21,60 +14,66 @@ module Prawn
     # @group Experimental API
 
     # Provides a way to execute a block of code repeatedly based on
-    # a page_filter.  Since Stamp is used under the hood, this method is very
+    # a `page_filter`. Since Stamp is used under the hood, this method is very
     # space efficient.
     #
-    # Available page filters are:
-    #   :all        -- repeats on every page
-    #   :odd        -- repeats on odd pages
-    #   :even       -- repeats on even pages
-    #   some_array  -- repeats on every page listed in the array
-    #   some_range  -- repeats on every page included in the range
-    #   some_lambda -- yields page number and repeats for true return values
-    #
     # Also accepts an optional second argument for dynamic content which
     # executes the code in the context of the filtered pages without using
     # a Stamp.
     #
-    # Example:
-    #
-    #   Prawn::Document.generate("repeat.pdf", :skip_page_creation => true) do
-    #
+    # @example
+    #   Prawn::Document.generate("repeat.pdf", skip_page_creation: true) do
     #     repeat :all do
-    #       draw_text "ALLLLLL", :at => bounds.top_left
+    #       draw_text "ALLLLLL", at: bounds.top_left
     #     end
     #
     #     repeat :odd do
-    #       draw_text "ODD", :at => [0,0]
+    #       draw_text "ODD", at: [0, 0]
     #     end
     #
     #     repeat :even do
-    #       draw_text "EVEN", :at => [0,0]
+    #       draw_text "EVEN", at: [0, 0]
     #     end
     #
-    #     repeat [1,2] do
-    #       draw_text "[1,2]", :at => [100,0]
+    #     repeat [1, 2] do
+    #       draw_text "[1, 2]", at: [100, 0]
     #     end
     #
     #     repeat 2..4 do
-    #       draw_text "2..4", :at => [200,0]
+    #       draw_text "2..4", at: [200, 0]
     #     end
     #
     #     repeat(lambda { |pg| pg % 3 == 0 }) do
-    #       draw_text "Every third", :at => [250, 20]
+    #       draw_text "Every third", at: [250, 20]
     #     end
     #
     #     10.times do
     #       start_new_page
-    #       draw_text "A wonderful page", :at => [400,400]
+    #       draw_text "A wonderful page", at: [400, 400]
     #     end
     #
-    #     repeat(:all, :dynamic => true) do
-    #       text page_number, :at => [500, 0]
+    #     repeat(:all, dynamic: true) do
+    #       text page_number, at: [500, 0]
     #     end
-    #
     #   end
     #
+    # @param page_filter [:all, :odd, :even, Array<Integer>, Range, Proc]
+    #   Pages to draw the repeater content on.
+    #
+    #   Available page filters are:
+    #
+    #   - `:all` -- repeats on every page.
+    #   - `:odd` -- repeats on odd pages.
+    #   - `:even` -- repeats on even pages.
+    #   - Array of Integers -- repeats on every page listed in the array.
+    #   - Range -- repeats on every page included in the range.
+    #   - Proc -- yields page number and repeats for true return values.
+    # @param options [Hash]
+    # @option options :dynamic [Boolean] (false)
+    #   A dynamic repeater executes block on every matched page. A static
+    #   repeater uses {stamp} to prepare the content (runs the block once) and
+    #   puts it on every matched page.
+    # @return [void]
     def repeat(page_filter, options = {}, &block)
       dynamic = options.fetch(:dynamic, false)
       repeaters << Prawn::Repeater.new(
@@ -83,10 +82,19 @@ module Prawn
     end
   end
 
-  class Repeater #:nodoc:
+  # Repeater object.
+  #
+  # @private
+  class Repeater
     class << self
       attr_writer :count
 
+      # Repeater counter.
+      #
+      # It's not an exact number of repeaters but a counter used to generate
+      # unique repeater stamp names.
+      #
+      # @return [Integer]
       def count
         @count ||= 0
       end
@@ -106,10 +114,18 @@ module Prawn
       Repeater.count += 1
     end
 
+    # Should this repeater run on this page?
+    #
+    # @param page_number [Integer]
+    # @return [Boolean]
     def match?(page_number)
       @document.page_match?(@page_filter, page_number)
     end
 
+    # Run repeater.
+    #
+    # @param page_number [Integer]
+    # @return [void]
     def run(page_number)
       if !@dynamic
         @document.stamp(@stamp_name) if match?(page_number)

data/lib/prawn/security/arcfour.rb

@@ -6,10 +6,6 @@
 #
 # "RC4" is a trademark of RSA Data Security, Inc.
 #
-# Copyright August 2009, Brad Ediger. All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 # @private
 class Arcfour
   def initialize(key)
@@ -38,6 +34,10 @@ class Arcfour
     @i = @j = 0
   end
 
+  # Encrypt string.
+  #
+  # @param string [String]
+  # @return [String]
   def encrypt(string)
     string.unpack('c*').map { |byte| byte ^ key_byte }.pack('c*')
   end