Various rdoc fixes and cleanups

lib/prawn/layout/grid.rb

@@ -1,14 +1,15 @@
 module Prawn
   class Document
-    # Defines the grid system for a particular document.  Takes the number of rows and columns and the
-    # width to use for the gutter as the keys :rows, :columns, :gutter
+    # Defines the grid system for a particular document.  Takes the number of
+    # rows and columns and the width to use for the gutter as the keys :rows,
+    # :columns, :gutter
     #
     def define_grid(options = {})
       @grid = Grid.new(self, options)
     end
 
-    # A method that can either be used to access a particular grid on the page or interogate the grid
-    # system directly.
+    # A method that can either be used to access a particular grid on the page
+    # or interogate the grid system directly.
     #
     #   @pdf.grid                 # Get the Grid directly
     #   @pdf.grid([0,1])          # Get the box at [0,1]
@@ -28,8 +29,8 @@ def grid(*args)
       end
     end
 
-    # A Grid represents the entire grid system of a Page and calculates the column width and row height
-    # of the base box.
+    # A Grid represents the entire grid system of a Page and calculates the
+    # column width and row height of the base box.
     class Grid
       attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
       # :nodoc
@@ -77,9 +78,9 @@ def set_gutter(options)
       end
     end
 
-    # A Box is a class that represents a bounded area of a page.  A Grid object has methods that allow
-    # easy access to the coordinates of its corners, which can be plugged into most existing prawn
-    # methods.
+    # A Box is a class that represents a bounded area of a page.  A Grid object
+    # has methods that allow easy access to the coordinates of its corners,
+    # which can be plugged into most existing prawn methods.
     #
     class Box
       attr_reader :pdf
@@ -90,7 +91,8 @@ def initialize(pdf, i, j)
         @j = j
       end
 
-      # Mostly diagnostic method that outputs the name of a box as col_num, row_num
+      # Mostly diagnostic method that outputs the name of a box as col_num,
+      # row_num
       def name
         "#{@i.to_s},#{@j.to_s}"
       end

lib/prawn/layout/page.rb

@@ -53,7 +53,7 @@ def padded_box(margin, &block)
     # Unless <tt>:width</tt> or <tt>:height</tt> are specified, the margin_box
     # width and height are used.
     #
-    #   header margin_box.top_left do
+    #  header margin_box.top_left do
     #    text "Here's My Fancy Header", :size => 25, :align => :center
     #    stroke_horizontal_rule
     #  end

lib/prawn/table.rb

@@ -82,38 +82,59 @@ class Table
 
     NUMBER_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+(?:[eE][+-]?\d+)?)?$/ #:nodoc:
 
-    # Creates a new Document::Table object. This is generally called
-    # indirectly through Document#table but can also be used explictly.
+    # Creates a new Document::Table object. This is generally called indirectly
+    # through Document#table but can also be used explictly.
     #
     # The <tt>data</tt> argument is a two dimensional array of strings,
     # organized by row, e.g. [["r1-col1","r1-col2"],["r2-col2","r2-col2"]].
     # As with all Prawn text drawing operations, strings must be UTF-8 encoded.
+    # Hashes can be used instead of Strings, in which case they are
+    # interpreted as Cell options (see Cell#new), and Cells can be used
+    # directly in table data as well.
     #
     # The following options are available for customizing your tables, with
     # defaults shown in [] at the end of each description.
     #
-    # <tt>:headers</tt>:: An array of table headers, either strings or Cells. [Empty]
-    # <tt>:align_headers</tt>:: Alignment of header text.  Specify for entire header (<tt>:left</tt>) or by column (<tt>{ 0 => :right, 1 => :left}</tt>). If omitted, the header alignment is the same as the column alignment.
+    # <tt>:headers</tt>::
+    #   An array of table headers, either strings or Cells. [Empty]
+    # <tt>:align_headers</tt>::
+    #   Alignment of header text.  Specify for entire header (<tt>:left</tt>)
+    #   or by column (<tt>{ 0 => :right, 1 => :left}</tt>). If omitted, the
+    #   header alignment is the same as the column alignment.
     # <tt>:header_text_color</tt>:: Sets the text color of the headers
     # <tt>:header_color</tt>:: Manually sets the header color
-    # <tt>:font_size</tt>:: The font size for the text cells . [12]
-    # <tt>:horizontal_padding</tt>:: The horizontal cell padding in PDF points [5]
+    # <tt>:font_size</tt>:: The default font size for the text cells. [12]
+    # <tt>:horizontal_padding</tt>::
+    #   The horizontal cell padding in PDF points [5]
     # <tt>:vertical_padding</tt>:: The vertical cell padding in PDF points [5]
     # <tt>:padding</tt>:: Horizontal and vertical cell padding (overrides both)
     # <tt>:border_width</tt>:: With of border lines in PDF points [1]
-    # <tt>:border_style</tt>:: If set to :grid, fills in all borders. If set to :underline_header, underline header only. Otherwise, borders are drawn on columns only, not rows
+    # <tt>:border_style</tt>::
+    #   If set to :grid, fills in all borders. If set to :underline_header,
+    #   underline header only. Otherwise, borders are drawn on columns only,
+    #   not rows
     # <tt>:border_color</tt>:: Sets the color of the borders.
-    # <tt>:position</tt>:: One of <tt>:left</tt>, <tt>:center</tt> or <tt>n</tt>, where <tt>n</tt> is an x-offset from the left edge of the current bounding box
-    # <tt>:width</tt>:: A set width for the table, defaults to the sum of all column widths
-    # <tt>:column_widths</tt>:: A hash of indices and widths in PDF points.  E.g. <tt>{ 0 => 50, 1 => 100 }</tt>
-    # <tt>:row_colors</tt>:: Used to specify background colors for rows. See below for usage.
-    # <tt>:align</tt>:: Alignment of text in columns, for entire table (<tt>:center</tt>) or by column (<tt>{ 0 => :left, 1 => :center}</tt>)
+    # <tt>:position</tt>::
+    #   One of <tt>:left</tt>, <tt>:center</tt> or <tt>n</tt>, where <tt>n</tt>
+    #   is an x-offset from the left edge of the current bounding box
+    # <tt>:width</tt>::
+    #   A set width for the table, defaults to the sum of all column widths
+    # <tt>:column_widths</tt>::
+    #   A hash of indices and widths in PDF points.  E.g. <tt>{ 0 => 50, 1 =>
+    #   100 }</tt>
+    # <tt>:row_colors</tt>::
+    #   Used to specify background colors for rows. See below for usage.
+    # <tt>:align</tt>::
+    #   Alignment of text in columns, for entire table (<tt>:center</tt>) or by
+    #   column (<tt>{ 0 => :left, 1 => :center}</tt>)
     #
     # Row colors (<tt>:row_colors</tt>) are specified as HTML hex color values,
     # e.g., "ccaaff". They can take several forms:
     #
-    # * An array of colors, used cyclically to "zebra stripe" the table: <tt>['ffffff', 'cccccc', '336699']</tt>.
-    # * A hash taking 0-based row numbers to colors: <tt>{ 0 => 'ffffff', 2 => 'cccccc'}</tt>.
+    # * An array of colors, used cyclically to "zebra stripe" the table:
+    #   <tt>['ffffff', 'cccccc', '336699']</tt>.
+    # * A hash taking 0-based row numbers to colors: <tt>{ 0 => 'ffffff', 2 =>
+    #   'cccccc'}</tt>.
     # * The symbol <tt>:pdf_writer</tt>, for PDF::Writer's default color scheme.
     #
     # See Document#table for typical usage, as directly using this class is
@@ -122,7 +143,8 @@ class Table
     def initialize(data, document, options={})
       unless data.all? { |e| Array === e }
         raise Prawn::Errors::InvalidTableData,
-          "data must be a two dimensional array of Prawn::Cells or strings"
+          "data must be a two dimensional array of Prawn::Table::Cells, " +
+          "Hashes, and Strings"
       end
 
       @data     = data
@@ -218,8 +240,8 @@ def fit_within_bounds(manual_widths, width)
       manual_widths.each { |k,v|
         @column_widths[k] = v; manual_width += v } if manual_widths
 
-      #Ensures that the maximum width of the document is not exceeded
-      #Takes into consideration the manual widths specified (With full manual
+      # Ensures that the maximum width of the document is not exceeded.  Takes
+      # into consideration the manual widths specified. (With full manual
       # widths specified, the width can exceed the document width as manual
       # widths are taken as gospel)
       max_width = width || @document.margin_box.width
@@ -386,7 +408,6 @@ def draw_page(contents)
       reset_row_colors
     end
 
-
     def next_row_color
       return if C(:row_colors).is_a?(Hash)
 

lib/prawn/table/cell.rb

@@ -32,12 +32,27 @@ class Table
     class Cell
 
       # Creates a new cell object.  Generally used indirectly via Document#cell
+      # (or by passing Strings or Hashes as Table data).
       #
-      # Of the available options listed below, <tt>:point</tt>, <tt>:width</tt>,
-      # and <tt>:text</tt> must be provided. If you are not using the
-      # Document#cell shortcut, the <tt>:document</tt> must also be provided.
+      # Cells can be used standalone, as a kind of limited-purpose bounding
+      # box for laying out blocks of text, or they can be a single field
+      # within a Table.
       #
-      # <tt>:point</tt>:: Absolute [x,y] coordinate of the top-left corner of the cell.
+      # The only initialization option that is always required is
+      # <tt>:text</tt>.
+      #
+      # When using a Cell by itself, you must specify <tt>:point</tt>, and
+      # <tt>:width</tt>.  Also, if creating the Cell directly rather than
+      # using the Document#cell shortcut, you must provide <tt>:document</tt>
+      # as well.
+      #
+      # When using a Cell as part of a table, many of the initialization
+      # options are ignored (<tt>:width</tt>, <tt>:horizontal_padding</tt>,
+      # <tt>:vertical_padding</tt>, <tt>:border_width</tt>,
+      # <tt>:border_style</tt>, <tt>:align</tt>).
+      #
+      # <tt>:point</tt>::
+      #   Absolute [x,y] coordinate of the top-left corner of the cell.
       # <tt>:document</tt>:: The Prawn::Document object to render on.
       # <tt>:text</tt>:: The text to be flowed within the cell
       # <tt>:text_color</tt>:: The color of the text to be displayed
@@ -46,42 +61,50 @@ class Cell
       # <tt>:horizontal_padding</tt>:: The horizontal padding in PDF points
       # <tt>:vertical_padding</tt>:: The vertical padding in PDF points
       # <tt>:padding</tt>:: Overrides both horizontal and vertical padding
-      # <tt>:align</tt>:: One of <tt>:left</tt>, <tt>:right</tt>, <tt>:center</tt>
-      # <tt>:borders</tt>:: An array of sides which should have a border. Any of <tt>:top</tt>, <tt>:left</tt>, <tt>:right</tt>, <tt>:bottom</tt>
+      # <tt>:align</tt>::
+      #   One of <tt>:left</tt>, <tt>:right</tt>, <tt>:center</tt>
+      # <tt>:borders</tt>::
+      #   An array of sides which should have a border.  Any of <tt>:top</tt>,
+      #   <tt>:left</tt>, <tt>:right</tt>, <tt>:bottom</tt>
       # <tt>:border_width</tt>:: The border line width. Defaults to 1.
-      # <tt>:border_style</tt>:: One of <tt>:all</tt>, <tt>:no_top</tt>, <tt>:no_bottom</tt>, <tt>:sides</tt>, <tt>:none</tt>, <tt>:bottom_only</tt>. Defaults to :all.
+      # <tt>:border_style</tt>::
+      #   One of <tt>:all</tt>, <tt>:no_top</tt>, <tt>:no_bottom</tt>,
+      #   <tt>:sides</tt>, <tt>:none</tt>, <tt>:bottom_only</tt>.  Defaults to
+      #   :all.
       # <tt>:border_color</tt>:: The color of the cell border.
       # <tt>:font_size</tt>:: The font size for the cell text.
       # <tt>:font_style</tt>:: The font style for the cell text.
+      # <tt>:colspan</tt>::
+      #   The number of columns that the cell should occupy in the table.
       #
       def initialize(options={})
-        @point        = options[:point]
-        @document     = options[:document]
-        @text         = options[:text].to_s
-        @text_color   = options[:text_color]
-        @width        = options[:width]
-        @height       = options[:height]
-        @borders      = options[:borders]
-        @border_width = options[:border_width] || 1
-        @border_style = options[:border_style] || :all
-        @border_color = options[:border_color]
-        @background_color = options[:background_color]
-        @align            = options[:align] || :left
-        @font_size        = options[:font_size]
-        @font_style       = options[:font_style]
-
+        @point              = options[:point]
+        @document           = options[:document]
+        @text               = options[:text].to_s
+        @text_color         = options[:text_color]
+        @width              = options[:width]
+        @height             = options[:height]
+        @borders            = options[:borders]
+        @border_width       = options[:border_width] || 1
+        @border_style       = options[:border_style] || :all
+        @border_color       = options[:border_color]
+        @background_color   = options[:background_color]
+        @align              = options[:align] || :left
+        @font_size          = options[:font_size]
+        @font_style         = options[:font_style]
+        @colspan            = options[:colspan]
         @horizontal_padding = options[:horizontal_padding] || 0
         @vertical_padding   = options[:vertical_padding]   || 0
 
         if options[:padding]
           @horizontal_padding = @vertical_padding = options[:padding]
         end
-
       end
 
       attr_accessor :point, :border_style, :border_width, :background_color,
                     :document, :horizontal_padding, :vertical_padding, :align,
-                    :borders, :text_color, :border_color, :font_size, :font_style
+                    :borders, :text_color, :border_color, :font_size,
+                    :font_style, :colspan
 
       attr_writer   :height, :width #:nodoc: