lib/prawn/text/formatted/box.rb in prawn-0.14.0 vs lib/prawn/text/formatted/box.rb in prawn-0.15.0

@@ -8,11 +8,12 @@
 #
 
 module Prawn
   module Text
     module Formatted
-
+      # @group Stable API
+      
       # Draws the requested formatted text into a box. When the text overflows
       # the rectangle shrink to fit or truncate the text. Text boxes are
       # independent of the document y position.
       #
       # == Formatted Text Array
@@ -98,23 +99,11 @@
       # vertical space was consumed by the printed text
       #
       class Box
         include Prawn::Text::Formatted::Wrap
 
-        def valid_options
-          PDF::Core::Text::VALID_OPTIONS + [:at, :height, :width,
-                                              :align, :valign,
-                                              :rotate, :rotate_around,
-                                              :overflow, :min_font_size,
-                                              :leading, :character_spacing,
-                                              :mode, :single_line,
-                                              :skip_encoding,
-                                              :document,
-                                              :direction,
-                                              :fallback_fonts,
-                                              :draw_text_callback]
-        end
+        # @group Experimental API
 
         # The text that was successfully printed (or, if <tt>dry_run</tt> was
         # used, the text that would have been successfully printed)
         attr_reader :text
 
@@ -143,46 +132,10 @@
 
         def line_gap
           line_height - (ascender + descender)
         end
 
-        #
-        # Example (see Prawn::Text::Core::Formatted::Wrap for what is required
-        # of the wrap method if you want to override the default wrapping
-        # algorithm):
-        #
-        #
-        #   module MyWrap
-        #
-        #     def wrap(array)
-        #       initialize_wrap([{ :text => 'all your base are belong to us' }])
-        #       @line_wrap.wrap_line(:document => @document,
-        #                            :kerning => @kerning,
-        #                            :width => 10000,
-        #                            :arranger => @arranger)
-        #       fragment = @arranger.retrieve_fragment
-        #       format_and_draw_fragment(fragment, 0, @line_wrap.width, 0)
-        #       []
-        #     end
-        #
-        #   end
-        #
-        #   Prawn::Text::Formatted::Box.extensions << MyWrap
-        #
-        #   box = Prawn::Text::Formatted::Box.new('hello world')
-        #   box.render('why can't I print anything other than' +
-        #              '"all your base are belong to us"?')
-        #
-        #
-        def self.extensions
-          @extensions ||= []
-        end
-
-        def self.inherited(base) #:nodoc:
-          extensions.each { |e| base.extensions << e }
-        end
-
         # See Prawn::Text#text_box for valid options
         #
         def initialize(formatted_text, options={})
           @inked             = false
           Prawn.verify_options(valid_options, options)
@@ -335,9 +288,61 @@
               end
             }
 
             draw_fragment_overlays(fragment)
           end
+        end
+
+        # @group Extension API
+        
+        # Example (see Prawn::Text::Core::Formatted::Wrap for what is required
+        # of the wrap method if you want to override the default wrapping
+        # algorithm):
+        #
+        #
+        #   module MyWrap
+        #
+        #     def wrap(array)
+        #       initialize_wrap([{ :text => 'all your base are belong to us' }])
+        #       @line_wrap.wrap_line(:document => @document,
+        #                            :kerning => @kerning,
+        #                            :width => 10000,
+        #                            :arranger => @arranger)
+        #       fragment = @arranger.retrieve_fragment
+        #       format_and_draw_fragment(fragment, 0, @line_wrap.width, 0)
+        #       []
+        #     end
+        #
+        #   end
+        #
+        #   Prawn::Text::Formatted::Box.extensions << MyWrap
+        #
+        #   box = Prawn::Text::Formatted::Box.new('hello world')
+        #   box.render('why can't I print anything other than' +
+        #              '"all your base are belong to us"?')
+        #
+        #
+        def self.extensions
+          @extensions ||= []
+        end
+
+        # @private
+        def self.inherited(base)
+          extensions.each { |e| base.extensions << e }
+        end
+
+        def valid_options
+          PDF::Core::Text::VALID_OPTIONS + [:at, :height, :width,
+                                              :align, :valign,
+                                              :rotate, :rotate_around,
+                                              :overflow, :min_font_size,
+                                              :leading, :character_spacing,
+                                              :mode, :single_line,
+                                              :skip_encoding,
+                                              :document,
+                                              :direction,
+                                              :fallback_fonts,
+                                              :draw_text_callback]
         end
 
         private
 
         def original_text