0
@@ -1,6 +1,44 @@
0
 module Prawn
0
+
0
+  class Document
0
+    # Builds and renders a Graphics::Cell.  A cell is essentially a
0
+    # special-purpose bounding box designed for flowing text within a bordered
0
+    # area.  For available options, see Graphics::Cell#new.
0
+    #
0
+    #    Prawn::Document.generate("cell.pdf") do
0
+    #       cell [100,500], 
0
+    #         :width => 200,
0
+    #         :text  => "The rain in Spain falls mainly on the plains"
0
+    #    end
0
+    #
0
+    def cell(point, options={})
0
+      Prawn::Graphics::Cell.new(options.merge(:document => self, :point => point)).draw
0
+    end
0
+  end
0
+
0
   module Graphics
0
+    # A cell is a special-purpose bounding box designed to flow text within a
0
+    # bordered area. This is used by Prawn's Document::Table implementation but
0
+    # can also be used standalone for drawing text boxes via Document#cell
0
+    #
0
     class Cell
0
+
0
+      # Creates a new cell object.  Generally used indirectly via Document#cell
0
+      #
0
+      # Of the available options listed below, <tt>:point</tt>, <tt>:width</tt>,
0
+      # and <tt>:text</tt> must be provided. If you are not using the
0
+      # Document#cell shortcut, the <tt>:document</tt> must also be provided.
0
+      #
0
+      # <tt>:point</tt>:: Absolute [x,y] coordinate of the top-left corner of the cell.
0
+      # <tt>:document</tt>:: The Prawn::Document object to render on. 
0
+      # <tt>:text</tt>:: The text to be flowed within the cell
0
+      # <tt>:width</tt>:: The width in PDF points of the cell.
0
+      # <tt>:border</tt>:: The border line width. If omitted, no border will be drawn.
0
+      # <tt>:horizontal_padding</tt>:: The horizontal padding in PDF points
0
+      # <tt>:vertical_padding</tt>:: The vertical padding in PDF points
0
+      # <tt>:padding</tt>:: Overrides both horizontal and vertical padding
0
+      # <tt>:border_style</tt>:: One of <tt>:all</tt>, <tt>:no_top<tt>, <tt>:no_bottom</tt>, <tt>:sides</tt>
0
+      #
0
       def initialize(options={})
0
         @point        = options[:point]
0
         @document     = options[:document]
0
@@ -18,27 +56,37 @@ module Prawn
0
       end
0
 
0
       attr_accessor :point, :border_style, :border
0
-      attr_writer   :height
0
+      attr_writer   :height #:nodoc:
0
 
0
+      # The width of the text area excluding the horizonal padding
0
+      #
0
       def text_area_width
0
         width - 2*@horizontal_padding
0
       end
0
 
0
+      # The width of the cell in PDF points
0
+      #
0
       def width
0
         @width || (@document.font_metrics.string_width(@text,
0
           @document.current_font_size)) + 2*@horizontal_padding
0
       end
0
 
0
+      # The height of the cell in PDF points
0
+      #
0
       def height
0
         @height || text_area_height + 2*@vertical_padding
0
       end
0
 
0
+      # The height of the text area excluding the vertical padding
0
+      #
0
       def text_area_height
0
         @document.font_metrics.string_height(@text, 
0
          :font_size  => @document.current_font_size, 
0
          :line_width => text_area_width) 
0
       end
0
 
0
+      # Draws the cell onto the PDF document
0
+      # 
0
       def draw
0
         rel_point = [@point[0] - @document.bounds.absolute_left,
0
                      @point[1] - @document.bounds.absolute_bottom]
0
@@ -82,6 +130,8 @@ module Prawn
0
         end
0
       end
0
 
0
+      private
0
+
0
       def borders
0
         @borders ||= case @border_style
0
         when :all
0
@@ -97,8 +147,10 @@ module Prawn
0
 
0
     end
0
 
0
-    # TODO: A temporary, entertaining name that should probably be changed.
0
-    class CellBlock
0
+    class CellBlock #:nodoc:
0
+
0
+      # Not sure if this class is something I want to expose in the public API.
0
+
0
       def initialize(document)
0
         @document = document
0
         @cells    = []
0
@@ -157,9 +209,4 @@ module Prawn
0
     end
0
   end
0
  
0
-  class Document
0
-    def cell(point, options={})
0
-      Prawn::Graphics::Cell.new(options.merge(:document => self, :point => point)).draw
0
-    end
0
-  end
0
 end