dyi 1.1.1 → 1.1.2

data/lib/dyi/chart/csv_reader.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -27,8 +27,48 @@ require 'nkf'
 module DYI
   module Chart
 
-    # CsvReader class provides a interface to CSV file and data for a chart
+    # +CsvReader+ class provides a interface to CSV file and data for a chart
     # object.
+    #
+    #= Basic Usage
+    #
+    # Using +PieChart+ and CsvReader, you can create the pie chart as the
+    # following:
+    #   # contents of asian_gdp.csv
+    #   # -------------------------
+    #   # China,5878
+    #   # Japan,5459
+    #   # India,1538
+    #   # South Koria,1007
+    #   # Other Countries, 2863
+    #   
+    #   require 'rubygems'
+    #   require 'dyi'
+    #   
+    #   reader = DYI::Chart::CsvReader.read('asian_gdp.csv',
+    #                                       :schema => [:name, :value],
+    #                                       :data_types => [:string, :number])
+    #   
+    #   # Creates the Pie Chart
+    #   chart = DYI::Chart::PieChart.new(450,250)
+    #   chart.load_data(reader)
+    #   chart.save('asian_gdp.svg')
+    # Creating the instance, you should not call +new+ method but {.read} method.
+    #
+    # The optional argument +:schema+ means a field name. See {ArrayReader} for
+    # +:schema+ option. The optional argument +:data_types+ means data types of
+    # the field. Using this option, +CsvReader+ converts text data that the CSV
+    # data included into a appropriate ruby object. (+:data_types+ option has
+    # been implemented in +ArrayReader+, although +ArrayReader+ ignores this
+    # option.) If +:data_types+ option is not specified, the values of all the
+    # fields are converted into instances of +Float+. +:data_types+ option can
+    # specify the following values: +:string+, +:decimal+, +:number+(synonym of
+    # +:decimal+), +:float+, +:integer+, +:date+, +:datetime+, +:boolean+
+    #
+    # See {CsvReader.read CsvReader.read} for other optional arguments.
+    # @see ArrayReader
+    # @see ArrayReader.read
+    # @since 0.0.0
     class CsvReader < ArrayReader
 
       # @private
@@ -37,6 +77,7 @@ module DYI
       # Parses CSV data and sets data.
       # @param [String] csv CSV data
       # @option (see ArrayReader#read)
+      # @option options [Array<Symbol>] :data_types array of field data types
       # @option options [String] :date_format date format string of CSV data,
       #   parsing a date string in CSV at +Date#strptime+
       # @option options [String] :datetime_format date-time format string of CSV
@@ -47,8 +88,10 @@ module DYI
       # @option options [String] :col_sep a separator of columns, default to
       #   <tt>","</tt>
       # @option options [String] :row_sep a separator of rows, default to
-      #   +:auto+ which means that a separetor is <tt>"\r\n"</tt>, <tt>"\n"</tt>,
-      #   or <tt>"\r"</tt> sequence
+      #   +:auto+, which means that a separetor is <tt>"\r\n"</tt>,
+      #   <tt>"\n"</tt>, or <tt>"\r"</tt> sequence
+      # @raise [ArgumentError] unknown encode is given for +:encode+
+      # @see ArrayReader#read
       # @since 1.1.1
       def parse(csv, options={})
         options = options.clone
@@ -75,6 +118,8 @@ module DYI
       # Parses CSV file and sets data.
       # @param [String] path a path of the CSV file
       # @option (see #parse)
+      # @raise (see #parse)
+      # @see (see #parse)
       def read(path, options={})
         parse(IO.read(path), options)
       end
@@ -112,8 +157,9 @@ module DYI
         # Parses CSV file and creates instance of CsvReader.
         # @param (see #read)
         # @option (see #read)
-        # @return [CsvReader] a new instance of CsvReader
-        # @see ArrayReader.read
+        # @return (see .parse)
+        # @raise (see #read)
+        # @see (see .parse)
         def read(path, options={})
           new.read(path, options)
         end
@@ -122,9 +168,11 @@ module DYI
         # @param (see #parse)
         # @option (see #parse)
         # @return [CsvReader] a new instance of CsvReader
+        # @raise (see #parse)
         # @see ArrayReader.read
-        def parse(path, options={})
-          new.parse(path, options)
+        # @since 1.1.1
+        def parse(csv, options={})
+          new.parse(csv, options)
         end
       end
     end

data/lib/dyi/chart/excel_reader.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -28,12 +28,28 @@ end
 require 'date'
 require 'nkf'
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+module DYI
+  module Chart
 
+    # +ExcelReader+ class provides a interface to Microsoft Excel file and data
+    # for a chart object. Creating the instance, you should not call +new+
+    # method but {.read} method.
+    #
+    # This class requires that _win32ole_ has been installed your system.
+    # @see ArrayReader
+    # @since 0.0.0
     class ExcelReader < ArrayReader
+
+      # @private
       OFFSET = DateTime.now.offset
 
+      # Parses Excel file and sets data.
+      # @param [String] path a path of the Excel file
+      # @option (see ArrayReader#read)
+      # @option options [String, Integer] :sheet sheet name of data source or
+      #   sheet number (starting from 1)
+      # @raise [NotImplementedError] _win32ole_ has not been installed
+      # @see ArrayReader#read
       def read(path, options={})
         if defined? WIN32OLE
           # for Windows
@@ -45,7 +61,7 @@ module DYI #:nodoc:
           sheet_values = sheet.range(sheet.cells(1,1), sheet.cells(range.end(4).row, range.end(2).column)).value
         else
           # except Windows
-          raise NotImplementedError, 'win32ole is not installed'
+          raise NotImplementedError, 'win32ole has not been installed'
         end
 
         begin
@@ -91,6 +107,13 @@ module DYI #:nodoc:
       end
 
       class << self
+
+        # Parses Excel file and creates instance of ExcelReader.
+        # @param (see #read)
+        # @option (see #read)
+        # @return [ExcelReader] a new instance of ExcelReader
+        # @raise (see #read)
+        # @see ArrayReader.read
         def read(path, options={})
           new.read(path, options)
         end

data/lib/dyi/chart/legend.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -19,14 +19,16 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+#
+module DYI
+  module Chart
 
+    # @since 0.0.0
     module Legend
 
       private
 
-      def draw_legend(names, shapes=nil, records=nil, colors=nil) #:nodoc:
+      def draw_legend(names, shapes=nil, records=nil, colors=nil)
         legend_canvas.translate(legend_point.x, legend_point.y)
         if show_legend?
           pen = Drawing::Pen.black_pen(:font => legend_font)
@@ -53,15 +55,15 @@ module DYI #:nodoc:
         end
       end
 
-      def legend_font_size #:nodoc:
+      def legend_font_size
         legend_font ? legend_font.draw_size : Font::DEFAULT_SIZE
       end
 
-      def default_legend_point #:nodoc:
+      def default_legend_point
         Coordinate.new(0,0)
       end
 
-      def default_legend_format #:nodoc:
+      def default_legend_format
         "{name}"
       end
 
@@ -69,7 +71,7 @@ module DYI #:nodoc:
 
         private
 
-        def included(klass) #:nodoc:
+        def included(klass)
           klass.__send__(:opt_accessor, :show_legend, :type => :boolean, :default => true)
           klass.__send__(:opt_accessor, :legend_font, :type => :font)
           klass.__send__(:opt_accessor, :legend_format, :type => :string, :default_method => :default_legend_format)

data/lib/dyi/chart/line_chart.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -19,9 +19,12 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+#
+module DYI
+
+  module Chart
 
+    # @since 0.0.0
     class LineChart < Base
       include AxisUtil
       include Legend
@@ -50,7 +53,6 @@ module DYI #:nodoc:
       opt_accessor :max_x_label_count, {:type => :integer, :default_proc => proc{|c| c.chart_width.div(Length.new(96))}}
       opt_accessor :show_x_labels, {:type => :boolean, :default => true}
       opt_accessor :legend_texts, {:type => :array, :item_type => :string}
-#      opt_accessor :data_columns, {:type => :array, :item_type => :integer}
       opt_accessor :use_effect, {:type => :boolean, :default => true}
       opt_accessor :bar_seriese_interval, {:type => :float, :default => 0.3}
       opt_accessor :color_columns, {:type => :array, :item_type => :integer}
@@ -141,18 +143,19 @@ module DYI #:nodoc:
         Drawing::Brush.new(:color => color)
       end
 
-      private
-
+      # @since 1.1.0
       def initialize(*args)
         super
         init_container
       end
 
-      def default_legend_point #:nodoc:
+      private
+
+      def default_legend_point
         Coordinate.new(margin_left, 0)
       end
 
-      def create_vector_image #:nodoc:
+      def create_vector_image
         super
 
         main_series_data = []
@@ -177,11 +180,12 @@ module DYI #:nodoc:
             second_axis_settings[:min],
             second_axis_settings[:max]) if use_y_second_axis?
 
-        data.values_size.times do |i|
-          draw_chart(i, chart_type(i), chart_color(i), use_y_second_axis?(i) ? sub_settings : settings) if chart_type(i) == :stackedbar
-        end
-        (data.values_size - 1).downto(0) do |i|
-          draw_chart(i, chart_type(i), chart_color(i), use_y_second_axis?(i) ? sub_settings : settings) if chart_type(i) != :stackedbar
+        [:stackedbar, :bar, :area, :line].each do |chart_type|
+          data.values_size.times do |i|
+            if chart_type(i) == chart_type
+              draw_chart(i, chart_type(i), chart_color(i), use_y_second_axis?(i) ? sub_settings : settings)
+            end
+          end
         end
 
         draw_axis(settings, sub_settings)
@@ -189,7 +193,7 @@ module DYI #:nodoc:
         draw_legend(texts, legend_shapes)
       end
 
-      def init_container #:nodoc:
+      def init_container
 #        mask = Drawing::ColorEffect::Mask.new(@canvas)
 #        mask.add_shapes(Shape::Rectangle.new(Drawing::Brush.new(:color => '#FFFFFF'), [margin_left, margin_top], chart_width, chart_height))
         @axis_back_canvas = Shape::ShapeGroup.draw_on(@canvas) unless @axis_back_canvas
@@ -206,7 +210,7 @@ module DYI #:nodoc:
         @chart_front_canvas.set_clipping(chart_clip)
       end
 
-      def draw_axis(settings, sub_settings) #:nodoc:
+      def draw_axis(settings, sub_settings)
         line_options = {:linecap => 'square'}
         line_pen = represent_3d? ? Drawing::CubicPen.new(line_options.merge(s_3d_pen_options)) : Drawing::Pen.new(line_options)
         sub_pen = represent_3d? ? Drawing::Pen.new : line_pen
@@ -218,7 +222,7 @@ module DYI #:nodoc:
         draw_scale(sub_pen, text_pen, settings, sub_settings, text_margin)
       end
 
-      def draw_y_axis(pen) #:nodoc:
+      def draw_y_axis(pen)
         if use_y_second_axis? || main_y_axis == :left
           start_point = [margin_left, height - margin_bottom]
           end_point = [margin_left, margin_top]
@@ -232,7 +236,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_scale(line_pen, text_pen, settings, sub_settings, text_margin) #:nodoc:
+      def draw_scale(line_pen, text_pen, settings, sub_settings, text_margin)
         if settings[:min] == settings[:min_scale_value] - settings[:scale_interval]
           y = value_position_on_chart(margin_top, settings, settings[:min], true)
           if use_y_second_axis? || main_y_axis == :left
@@ -321,7 +325,7 @@ module DYI #:nodoc:
         i % ((data.records_size - 1) / [max_x_label_count - 1, 1].max) == 0
       end
 
-      def draw_x_axis(main_pen, sub_pen, text_pen, text_margin) #:nodoc:
+      def draw_x_axis(main_pen, sub_pen, text_pen, text_margin)
         main_pen.draw_line(represent_3d? ? @axis_back_canvas : @axis_front_canvas, [margin_left, height - margin_bottom], [width - margin_right, height - margin_bottom])
 
         data.records_size.times do |i|
@@ -342,7 +346,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_chart(id, chart_type, color, settings) #:nodoc:
+      def draw_chart(id, chart_type, color, settings)
         case chart_type
           when :line then draw_line(id, color, settings)
           when :area then draw_area(id, color, settings)
@@ -351,7 +355,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_line(id, color, settings) #:nodoc:
+      def draw_line(id, color, settings)
         values = data.series(id)
         return if values.compact.size == 0
         first_index = values.each_with_index {|value, i| break i if value}
@@ -371,7 +375,7 @@ module DYI #:nodoc:
         pen.linejoin = 'bevel'
       end
 
-      def draw_area(id, color, settings) #:nodoc:
+      def draw_area(id, color, settings)
         values = data.series(id)
         return if values.compact.size == 0
         first_index = values.each_with_index {|value, i| break i if value}
@@ -391,7 +395,7 @@ module DYI #:nodoc:
         polygone.translate(back_translate_value[:dx], back_translate_value[:dy]) if represent_3d?
       end
 
-      def draw_bar(id, color, settings) #:nodoc:
+      def draw_bar(id, color, settings)
         bar_group = Shape::ShapeGroup.new(@chart_options).draw_on(@chart_front_canvas)
         values = data.series(id)
         return if values.compact.size == 0
@@ -409,7 +413,7 @@ module DYI #:nodoc:
         bar_group.translate(back_translate_value[:dx] / 2, back_translate_value[:dy] / 2) if represent_3d?
       end
 
-      def draw_stackedbar(id, color, settings) #:nodoc:
+      def draw_stackedbar(id, color, settings)
         bar_group = Shape::ShapeGroup.new(@chart_options).draw_on(@chart_front_canvas)
 
         values = data.series(id)
@@ -433,14 +437,14 @@ module DYI #:nodoc:
       end
 
       # @since 1.0.0
-      def chart_color(index) #:nodoc:
+      def chart_color(index)
         if chart_colors
           color = chart_colors[index]
         end
         color || DEFAULT_CHART_COLOR[index % DEFAULT_CHART_COLOR.size]
       end
 
-      def legend_shapes #:nodoc:
+      def legend_shapes
         result = []
         (0...data.values_size).each_with_index do |id, index|
           result <<

data/lib/dyi/chart/pie_chart.rb

@@ -1,6 +1,6 @@
 # -*- encoding: UTF-8 -*-
 
-# Copyright (c) 2009-2011 Sound-F Co., Ltd. All rights reserved.
+# Copyright (c) 2009-2012 Sound-F Co., Ltd. All rights reserved.
 #
 # Author:: Mamoru Yuo
 #
@@ -19,43 +19,205 @@
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
 
-module DYI #:nodoc:
-  module Chart #:nodoc:
+#
+module DYI
+  module Chart
 
+    # +PieChart+ creates the image of pie chart.
+    #
+    #= Basic Usage
+    #
+    # Using +PieChart+ and ArrayReader (or sub class of ArrayReader), you can
+    # create the pie chart as the following:
+    #   require 'rubygems'
+    #   require 'dyi'
+    #   
+    #   # Nominal GDP of Asian Countries (2010)
+    #   chart_data = [['China', 5878],
+    #                 ['Japan', 5459],
+    #                 ['India', 1538],
+    #                 ['South Koria', 1007],
+    #                 ['Other Countries', 2863]]
+    #   reader = DYI::Chart::ArrayReader.read(chart_data, :schema => [:name, :value])
+    #
+    #   # Creates the Pie Chart
+    #   chart = DYI::Chart::PieChart.new(450,250)
+    #   chart.load_data(reader)
+    #   chart.save('asian_gdp.svg')
+    # See {ArrayReader} about how to set the chart data.
+    #
+    # The chart options of +PieChart+ are specified at the constractor. See
+    # <em>Instance Attribute</em> of this class, {Base} and {Legend} for the
+    # attributes that can be specified. The specified attributes can be refered
+    # and set.
+    #   # Creates the Pie Chart
+    #   chart = DYI::Chart::PieChart.new(500,250,
+    #             :center_point => [130, 100],
+    #             :legend_point => [250, 50],
+    #             :represent_3d => true,
+    #             :_3d_settings => {:dy => 20},
+    #             :legend_format => "{?name}\t{!e}{?value:#,0}\t{!e}({?percent:0.0%})",
+    #             :chart_stroke_color => 'white')
+    #   puts chart.represent_3d?    # => true
+    #   chart.show_baloon = false
+    #   puts chart.show_baloon?     # => false
+    #
+    #   chart.load_data(reader)
+    #   chart.save('asian_gdp.svg')
+    #
+    #= Adds Custom Elements to Chart
+    #
+    # Using {#canvas canvas} attribute, you can add arbitrary graphical elements.
+    #   # Creates the Pie Chart
+    #   chart = DYI::Chart::PieChart.new(500,250,
+    #             :center_point => [130, 100],
+    #             :legend_point => [250, 50],
+    #             :represent_3d => true,
+    #             :_3d_settings => {:dy => 20},
+    #             :legend_format => "{?name}\t{!e}{?value:#,0}\t{!e}({?percent:0.0%})",
+    #             :chart_stroke_color => 'white')
+    #
+    #   DYI::Drawing::Pen.black_pen.draw_text(chart.canvas,
+    #             [250, 20],
+    #             'Nominal GDP of Asian Countries (2010)',
+    #             :text_anchor => 'middle')
+    #   chart.load_data(reader)
+    #   chart.save('asian_gdp.svg')
+    # @see LineChart
+    # @see ArrayReader
+    # @since 0.0.0
     class PieChart < Base
       include Legend
 
-      attr_reader :chart_canvas, :data_label_canvas, :legend_canvas
-
-      opt_accessor :center_point, {:type => :point, :default_method => :default_center_point}
-      opt_accessor :chart_radius_x, {:type => :length, :default_method => :default_chart_radius_x}
-      opt_accessor :chart_radius_y, {:type => :length, :default_method => :default_chart_radius_y}
-      opt_accessor :inner_radius, {:type => :float, :default => 0.0, :range => 0.0 ... 1.0}
-      opt_accessor :represent_3d, {:type => :boolean}
-      opt_accessor :_3d_settings, {:type => :hash, :default => {}, :keys => [:dy], :item_type => :float}
-      opt_accessor :chart_colors, {:type => :array, :item_type => :color}
-      opt_accessor :chart_stroke_color, {:type => :color}
-      opt_accessor :chart_stroke_width, {:type => :float, :default => 1}
-      opt_accessor :moved_elements, {:type => :array, :item_type => :float}
+      # Returns the container element which body of chart is drawn on.
+      # @return [Shape::ShapeGroup]  the container element which chart parts is
+      #   drawn on
+      attr_reader :chart_canvas
+
+      # Returns the container element which data labels is drawn on.
+      # @return [Shape::ShapeGroup]  the container element which chart parts is
+      #   drawn on
+      attr_reader :data_label_canvas
+
+      # Returns the container element which legend is drawn on.
+      # @return [Shape::ShapeGroup]  the container element which chart parts is
+      #   drawn on
+      attr_reader :legend_canvas
+
+      # Returns or sets the center point of the pie chart.
+      opt_accessor :center_point, :type => :point, :default_method => :default_center_point
+
+      # Returns or sets the x-axis radius of the pie chart.
+      opt_accessor :chart_radius_x, :type => :length, :default_method => :default_chart_radius_x
+
+      # Returns or sets the y-axis radius of the pie chart.
+      opt_accessor :chart_radius_y, :type => :length, :default_method => :default_chart_radius_y
+
+      # Returns or sets the ratio of inner radius to outer radius of the
+      # doughnut chart. The value of +inner_radius+ should be a positive number
+      # or zero less than 1.0. Defalt to 0.0 (that means that chart is not
+      # doughnut).
+      opt_accessor :inner_radius, :type => :float, :default => 0.0, :range => 0.0 ... 1.0
+
+      # Returns or sets whether the chart is made three-dimensional. Defalt to
+      # false.
+      opt_accessor :represent_3d, :type => :boolean
+
+      # Returns or sets the three-demenal setting hash.
+      # This attribute is valid if the +respond_3d+ attribute equals true.
+      # The hash includes the following key:
+      # [+:dy+] ({Length}) the thickness of the pie
+      opt_accessor :_3d_settings, :type => :hash, :default => {}, :keys => [:dy], :item_type => :length
+
+      # Returns or sets specific colors for the slices.
+      opt_accessor :chart_colors, :type => :array, :item_type => :color
+
+      # Returns or sets the color of the outline of the slices.
+      opt_accessor :chart_stroke_color, :type => :color
+
+      # Returns or sets the width of the outline of the slices. Default to 1.0.
+      opt_accessor :chart_stroke_width, :type => :float, :default => 1.0
+
+      # Returns or sets the array of the ratio of the distance which the slices
+      # are moved from the center to the outside.
+      opt_accessor :moved_elements, :type => :array, :item_type => :float
+
+      # Returns or sets the CSS class of the pie area.
       opt_accessor :pie_css_class, :type => :string
-      opt_accessor :show_data_label, {:type => :boolean, :default => true}
+
+      # Returns or sets whether the data labels are shown. Defalt to true.
+      opt_accessor :show_data_label, :type => :boolean, :default => true
+
+      # Returns or sets the CSS class of the data labels.
       opt_accessor :data_label_css_class, :type => :string
-      opt_accessor :data_label_position, {:type => :float, :default => 0.8}
-      opt_accessor :data_label_font, {:type => :font}
-      opt_accessor :data_label_format, {:type => :string, :default => "{?name}"}
-      opt_accessor :hide_data_label_ratio, {:type => :float, :default => 0.00}
+
+      # Returns or sets the position of the data labels. Zero means the data
+      # labels are shown at the center point, and 1.0 means they are shown on
+      # the circumference of the pie. Default to 0.8.
+      opt_accessor :data_label_position, :type => :float, :default => 0.8
+
+      # Returns or sets the font of the data labels.
+      opt_accessor :data_label_font, :type => :font
+
+      # Returns or sets the format string of the data labels. Default to <tt>"{?name}"</tt>.
+      opt_accessor :data_label_format, :type => :string, :default => "{?name}"
+
+      # Returns or sets the value to control showing the data labels. If the
+      # slice's percentage of the pie is less than this value, its label is not
+      # shown. Default to 0.0 (it means all the labels are shown).
+      opt_accessor :hide_data_label_ratio, :type => :float, :default => 0.0
+
+      # Returns or sets whether the baloons are shown when the mouse is over the
+      # slices. Defalt to true.
       opt_accessor :show_baloon, :type => :boolean, :default => true
+
+      # Returns or sets the font of the baloons.
       opt_accessor :baloon_font, :type => :font
-      opt_accessor :baloon_position, {:type => :float, :default => 0.8}
+
+      # Returns or sets the position of the baloons. Zero means the baloons are
+      # shown at the center point, and 1.0 means they are shown on the
+      # circumference of the pie. Default to 0.8.
+      opt_accessor :baloon_position, :type => :float, :default => 0.8
+
+      # Returns or sets the format string of the baloons. Default to
+      # <tt>"{?name}\n{?value}"</tt>.
       opt_accessor :baloon_format, :type => :string, :default => "{?name}\n{?value}"
+
+      # Returns or sets the hash of the vertical and horizontal paddings of the
+      # baloons. The hash includes the following key:
+      # [+:vertical+] ({Length}) the vertical padding of the baloons
+      # [+:horizontal+] ({Length}) the horizontal padding of the baloons
       opt_accessor :baloon_padding, :type => :hash, :default => {}, :keys => [:vertical, :horizontal], :item_type => :length
+
+      # Returns or sets the radius of the circle used to round off the corners
+      # of the baloons.
       opt_accessor :baloon_round, :type => :length, :default => 6
+
+      # Returns or sets the background color of the baloons. If this property
+      # has been set, the background color of all the baloons is the setting
+      # value. If +baloon_background_colors+ property has been set, the setting
+      # of +baloon_background_colors+ property is applied.
       opt_accessor :baloon_background_color, :type => :color
+
+      # Returns or sets the background colors of the baloons of the each slices.
       opt_accessor :baloon_background_colors, :type => :array, :item_type => :color
+
+      # Returns or sets the border color of the baloons. If this property has
+      # been set, the border color of all the baloons is the setting value. If
+      # +baloon_border_colors+ property has been set, the setting of
+      # +baloon_border_colors+ property is applied.
       opt_accessor :baloon_border_color, :type => :color
+
+      # Returns or sets the border colors of the baloons of the each slices.
       opt_accessor :baloon_border_colors, :type => :array, :item_type => :color
+
+      # Returns or sets the border width of the baloons.
       opt_accessor :baloon_border_width, :type => :length, :default => 2
+
+      # Returns or sets the CSS class of the baloons.
       opt_accessor :baloon_css_class, :type => :string
+
+      # Returns or sets the duration of the animations.
       opt_accessor :animation_duration, :type => :float, :default => 0.5
 
       def back_translate_value
@@ -78,20 +240,20 @@ module DYI #:nodoc:
 
       private
 
-      def default_center_point #:nodoc:
+      def default_center_point
         margin = [width - chart_radius_x * 2, height - chart_radius_y * 2].min.quo(2)
         Coordinate.new(margin + chart_radius_x, margin + chart_radius_y)
       end
 
-      def default_chart_radius_x #:nodoc:
+      def default_chart_radius_x
         [width, height].min * 0.4
       end
 
-      def default_chart_radius_y #:nodoc:
+      def default_chart_radius_y
         represent_3d? ? chart_radius_x.quo(2) : chart_radius_x
       end
 
-      def default_legend_point #:nodoc:
+      def default_legend_point
         if width - chart_radius_x * 2 < height - chart_radius_y * 2
           Coordinate.new(width * 0.1, chart_radius_y * 2 + (width - chart_radius_x * 2) * 0.8)
         else
@@ -99,11 +261,11 @@ module DYI #:nodoc:
         end
       end
 
-      def default_legend_format #:nodoc:
+      def default_legend_format
         "{?name}\t{?percent}"
       end
 
-      def create_vector_image #:nodoc:
+      def create_vector_image
         super
         if represent_3d?
           brush = Drawing::ColumnBrush.new(back_translate_value.merge(chart_stroke_color ? {:stroke_width => chart_stroke_width, :stroke => chart_stroke_color} : {}))
@@ -168,7 +330,7 @@ module DYI #:nodoc:
         end
       end
 
-      def draw_chart(brush, record, accumulation, total_value, index) #:nodoc:
+      def draw_chart(brush, record, accumulation, total_value, index)
         canvas = Shape::ShapeGroup.draw_on(@chart_canvas)
         attrs = {}
         if data.has_field?(:css_class) && (css_class = record.css_class)
@@ -231,7 +393,7 @@ module DYI #:nodoc:
           text = Drawing::Pen.black_pen(:font => baloon_font, :opacity => 0.0).draw_text(
               @data_label_canvas,
               center_point + baloon_point,
-              format_string(data_label_format, record, total_value),
+              format_string(baloon_format, record, total_value),
               baloon_options)
           text.add_painting_animation(:to => {:opacity => 1},
                                       :duration => animation_duration,
@@ -321,6 +483,7 @@ module DYI #:nodoc:
         end
       end
 
+      # @since 1.0.0
       def format_string(format, record, total_value)
         format = format.gsub(/\A\{!(\w)\}/, '')
         format.gsub(/\{\?((?![0-9])\w+)(:[^}]*)?\}/){|m|