dyi 1.1.0 → 1.1.1

data/lib/dyi/element.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
 #
@@ -18,20 +18,26 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with DYI.  If not, see <http://www.gnu.org/licenses/>.
-#
-# == Overview
-#
-# This file provides the DYI::Element class, which is abstract base class of
-# DYI::Canvas and DYI::Shape::Base.
-#
-# @since 1.0.0
 
-module DYI #:nodoc:
+module DYI
 
+  # Abstract class that represents a element contained in the image.
+  # @abstract
+  # @since 1.0.0
   class Element
     extend AttributeCreator
     ID_REGEXP = /\A[:A-Z_a-z][\-\.0-9:A-Z_a-z]*\z/
 
+    # Returns a title of the element.
+    # @return [String] a title of the element
+    # @since 1.1.1
+    attr_accessor :title
+
+    # Returns a description of the element.
+    # @return [String] a description of the element
+    # @since 1.1.1
+    attr_accessor :description
+
     # Returns id for the element. If the element has no id yet, makes id and
     # returns it.
     # @return [String] id for the element
@@ -58,7 +64,7 @@ module DYI #:nodoc:
       @id = value.to_s
     end
 
-    # Returns the canvas where the shape is drawn
+    # Returns the canvas where the shape is drawn.
     # @return [Canvas] the canvas where the shape is drawn
     def canvas
       current_node = self
@@ -68,24 +74,41 @@ module DYI #:nodoc:
       end
     end
 
+    # Returns an array of child elements.
+    # @return [Array<Element>] an empty array
     def child_elements
       []
     end
 
+    # Returns whether the element has reference of external file.
+    # @return [Boolean] always false
     def include_external_file?
       false
     end
 
-    # @return [Boolean] whether the element has a URI reference
+    # Returns whether the element has URI reference.
+    # @return [Boolean] always false
     def has_uri_reference?
       false
     end
   end
 
+  # Abstract class that represents a graphic element.
+  # @abstract
+  # @since 1.0.0
   class GraphicalElement < Element
+
+    # Returns a CSS class attribute of the element.
+    # @return [String] a class name or set of class names. If the elements has
+    #   multiple class names, class names are separated by white space
     attr_reader :css_class
+
     CLASS_REGEXP = /\A[A-Z_a-z][\-0-9A-Z_a-z]*\z/
 
+    # Sets a CSS class attribute.
+    # @param [String] css_class a CSS class attribute
+    # @see {#css_class}
+    # @raise [ArgumentError] parameter `css_class' is illegal class name
     def css_class=(css_class)
       return @css_class = nil if css_class.nil?
       classes = css_class.to_s.split(/\s+/)
@@ -97,10 +120,17 @@ module DYI #:nodoc:
       @css_class = classes.join(' ')
     end
 
+    # Returns an array of CSS class names.
+    # @return [Array<String>] an array of CSS class names
     def css_classes
       css_class.to_s.split(/\s+/)
     end
 
+    # Adds a CSS class.
+    # @param [String] css_class a CSS class name
+    # @return [String, nil] value of parameter `css_class' if successes to add
+    #   a class, nil if failures
+    # @raise [ArgumentError] parameter `css_class' is illegal class name
     def add_css_class(css_class)
       if css_class.to_s !~ CLASS_REGEXP
         raise ArgumentError, "`#{css_class}' is a illegal class-name"
@@ -112,6 +142,10 @@ module DYI #:nodoc:
       css_class
     end
 
+    # Remove a CSS class.
+    # @param [String] css_class a CSS class name that will be removed
+    # @return [String, nil] value of parameter `css_class' if successes to
+    #   remove a class, nil if failures
     def remove_css_class(css_class)
       classes = css_classes
       if classes.delete(css_class.to_s)
@@ -122,29 +156,30 @@ module DYI #:nodoc:
       end
     end
 
-    # Returns event listeners that is associated with the element
+    # Returns event listeners that is associated with the element.
+    # @return [Hash] hash of event listeners
     def event_listeners
       @event_listeners ||= {}
     end
 
-    # Adds a animation of painting to the element
-    # @param [Event] an event that is set to the element
-    # @return [void]
+    # Adds a animation of painting to the element.
+    # @param [Event] event an event that is set to the element
+    # @return [String] id for this element
     def set_event(event)
       @events ||= []
       @events << event
       publish_id
     end
 
-    # @return [Boolean] whether event is set to the element
+    # Returns whether an event is set to the element.
+    # @return [Boolean] true if an event is set to the element, false otherwise
     def event_target?
       !(@events.nil? || @events.empty?)
     end
 
-    # Associates the element with a event listener
+    # Associates the element with a event listener.
     # @param [Symbol] event_name a event name
     # @param [Script::SimpleScript] event_listener a event listener
-    # @return [void]
     def add_event_listener(event_name, event_listener)
       event_listener.related_to(DYI::Event.new(event_name, self))
       if event_listeners.key?(event_name)
@@ -161,7 +196,6 @@ module DYI #:nodoc:
     # Removes asociation with given event listener
     # @param [Symbol] event_name a event name
     # @param [Script::SimpleScript] event_listener a event listener
-    # @return [void]
     def remove_event_listener(event_name, event_listener)
       if event_listeners.key?(event_name)
         event_listeners[event_name].delete(event_listener)

data/lib/dyi/event.rb

@@ -60,7 +60,6 @@ module DYI
     # Sets a event listener.
     # @param [Script::EcmaScript::EventListener] event_listener a script to be
     #           called when the event occurs
-    # @return [void]
     def set_listener(event_listener)
       target.add_event_listener(event_name, event_listener)
       event_listener.related_to(self)
@@ -69,7 +68,6 @@ module DYI
     # Removes a event listener.
     # @param [Script::EcmaScript::EventListener] event_listener a script that
     #           is removed
-    # @return [void]
     def remove_listener(event_listener)
       target.remove_event_listener(event_name, event_listener)
       event_listener.unrelated_to(self)

data/lib/dyi/formatter/svg_formatter.rb

@@ -27,7 +27,7 @@ module DYI #:nodoc:
     class SvgFormatter < XmlFormatter
 
       def initialize(canvas, options={})
-        super(canvas, options)
+        super
         version = options[:version] || '1.1'
         unless ['1.0', '1.1'].include?(@version = version.to_s)
           raise ArgumentError, "version `#{version}' is unknown version"
@@ -79,6 +79,15 @@ module DYI #:nodoc:
         end
         sio = StringIO.new
         create_node(sio, 'svg', attrs) {
+          create_leaf_node(sio, 'title', canvas.title) if canvas.title
+          create_leaf_node(sio, 'desc', canvas.description) if canvas.description
+          if canvas.metadata
+            create_cdata_node(sio, 'metadata'){
+              puts_line(sio) {
+                write_metadata(canvas.metadata, sio)
+              }
+            }
+          end
           @root_info = [sio.pos, @level]
           i = 0
           length = canvas.scripts.size
@@ -433,8 +442,10 @@ module DYI #:nodoc:
 
       # @since 1.0.0
       def write_shape_node(shape, io, attrs, tag_name, &create_child_node)
-        if shape.animate? || block_given?
+        if shape.title || shape.description || shape.animate? || block_given?
           create_node(io, tag_name, attrs) {
+            create_leaf_node(io, 'title', shape.title) if shape.title
+            create_leaf_node(io, 'desc', shape.description) if shape.description
             yield if block_given?
             write_animations(shape, io)
           }
@@ -452,6 +463,61 @@ module DYI #:nodoc:
         end
       end
 
+      # @since 1.1.1
+      def write_metadata(metadata, io)
+        case metadata
+        when String, Symbol
+          io << '"'
+          metadata.to_s.unpack('U*').each do |c|
+            case c
+              when 0x08 then io << '\\b'  # backspace
+              when 0x09 then io << '\\t'  # horizontal tab
+              when 0x0a then io << '\\n'  # line feed
+              when 0x0c then io << '\\f'  # form feed
+              when 0x0d then io << '\\r'  # carriage return
+              when 0x22 then io << '\\"'  # double quote
+              when 0x5c then io << '\\\\' # backslash
+              when (0x20..0x7e) then io << c.chr
+              else io << '\\u' << ('%04X' % c)
+            end
+          end
+          io << '"'
+        when Integer, TrueClass, FalseClass
+          io << metadata.inspect
+        when NilClass
+          io << 'null'
+        when Numeric
+          io << metadata.to_f.to_s
+        when Hash
+          io << '{'
+          metadata.keys.each_with_index do |key, i|
+            io << ',' unless i == 0
+            write_metadata(key.to_s, io)
+            io << ':'
+            write_metadata(metadata[key], io)
+          end
+          io << '}'
+        when Struct
+          io << '{'
+          metadata.members.each_with_index do |key, i|
+            io << ',' unless i == 0
+            write_metadata(key.to_s, io)
+            io << ':'
+            write_metadata(metadata.__send__(key), io)
+          end
+          io << '}'
+        when Enumerable
+          io << '['
+          metadata.each_with_index do |value, i|
+            io << ',' unless i == 0
+            write_metadata(value, io)
+          end
+          io << ']'
+        else
+          write_metadata(metadata.to_s, io)
+        end
+      end
+
       # @since 1.0.0
       def create_border_node(shape, io)
         if shape.attributes[:show_border]
@@ -467,7 +533,6 @@ module DYI #:nodoc:
 
       # Examines the descendant elements of the canvas to collect the
       # information of the elements.
-      # @return [void]
       # @since 1.0.0
       def pre_write
         if @canvas.scripts.any?{|script| script.has_uri_reference?}
@@ -526,7 +591,6 @@ module DYI #:nodoc:
         [amin_event(shape, event), anim_duration(offset)].compact.join('+')
       end
 
-      # @return [void]
       # @since 1.0.0
       def merge_anim_attributes(anim, shape, attrs) #:nodoc:
         attrs[:dur] = anim_duration(anim.duration) if anim.duration && anim.duration != 0

data/lib/dyi/script/ecmascript.rb

@@ -35,6 +35,42 @@ module DYI
       # This Module includes helper methods for generating a client-script.
       # These methods generate a script that conforms to DOM Level 2 (W3C
       # Recommendation).
+      #
+      # All the methods defined by the module are `module functions', which are
+      # called as private instance methods and are also called as public class
+      # methods (they are methods of Math Module like).
+      # In the following example, +get_element+ method is called as a
+      # private instance method.
+      #   class Foo
+      #     include DYI::Script::EcmaScript::DomLevel2
+      #     def bar
+      #       puts get_element('el_id') # => "document.getElementById(\"el_id\")"
+      #     end
+      #   end
+      # At the toplevel, it is able to include the module.
+      #   include DYI::Script::EcmaScript::DomLevel2
+      #   puts get_element('el_id')     # => "document.getElementById(\"el_id\")"
+      # In the Next example, +get_element+ method is called as a public class
+      # method.
+      #   puts DYI::Script::EcmaScript::DomLevel2.get_element('el_id')
+      #                                 # => "document.getElementById(\"el_id\")"
+      #
+      #= Module Function List
+      #
+      # {#add_event_listener}, {#draw_text_border}, {#form_legend_labels},
+      # {#get_attribute}, {#get_element}, {#metadata_parse_json},
+      # {#rewrite_text}, {#set_attribute}, {#to_ecmascript_string}
+      #
+      # {render:#add_event_listener}
+      # {render:#dispatch_evnet}
+      # {render:#draw_text_border}
+      # {render:#form_legend_labels}
+      # {render:#get_attribute}
+      # {render:#get_element}
+      # {render:#metadata_parse_json}
+      # {render:#rewrite_text}
+      # {render:#set_attribute}
+      # {render:#to_ecmascript_string}
       module DomLevel2
 
         private
@@ -62,6 +98,33 @@ module DYI
           parts.join
         end
 
+        # Returns an ECMAScript value of a metadata that this image has.
+        # @return [String] a string that means 
+        # @since 1.1.1
+        # @api function
+        def metadata_parse_json
+=begin
+script =<<-EOS
+(function() {
+  var metadata_element = document.getElementsByTagName("metadata").item(0);
+  if(metadata_element == null)
+    return null;
+  var metadata_contents = [];
+  for(var i=0, length=metadata_element.childNodes.length; i<length; i++) {
+    var child = metadata_element.childNodes.item(i);
+    if(child.nodeType!=3&&child.nodeType!=4)
+      return null;
+    metadata_contents.push(child.data);
+  }
+  if(metadata_contents.length == 0)
+    return null;
+  return JSON.parse(metadata_contents.join(""));
+})()
+EOS
+=end
+          '(function(){var a=document.getElementsByTagName("metadata").item(0);if(a==null)return null;var b=[];for(var c=0,d=a.childNodes.length;c<d;c++){var e=a.childNodes.item(c);if(e.nodeType!=3&&e.nodeType!=4)return null;b.push(e.data);}if(b.length==0)return null;return JSON.parse(b.join(""));})()'
+        end
+
         # Returns an ECMAScript value of attribute of the element.
         # @param [Element|String] element the target element or id of the target
         # element
@@ -70,7 +133,7 @@ module DYI
         # @example
         #   rect = pen.draw_rectange(canvas, [0, 0], 20, 30, :id => "rect1")
         #   get_attribute(rect, "width")
-        #        # => "document.getElementById(\"rect1\").getAttribute(\"x\")"
+        #        # => "document.getElementById(\"rect1\").getAttribute(\"width\")"
         # @since 1.1.0
         def get_attribute(element, attribute_name)
           "#{get_element(element)}.getAttribute(\"#{attribute_name}\")"
@@ -325,7 +388,6 @@ EOS
 
         # Relates this object to an event.
         # @param [Event] event an event that is related to
-        # @return [void]
         def related_to(event)
           unless @events.include?(event)
             @events << event
@@ -334,7 +396,6 @@ EOS
 
         # Removes the relation to an event.
         # @param [Event] event an event that is removed the relation to
-        # @return [void]
         def unrelated_to(event)
           @events.delete(event)
         end

data/lib/dyi/script/simple_script.rb

@@ -76,7 +76,6 @@ module DYI
       # Writes the buffer contents of the object.
       # @param [Formatter::Base] a formatter for export
       # @param [IO] io a buffer that is written
-      # @return [void]
       def write_as(formatter, io=$>)
         formatter.write_script(self, io)
       end

data/lib/dyi/shape/base.rb

@@ -21,22 +21,50 @@
 
 require 'enumerator'
 
-module DYI #:nodoc:
-  module Shape #:nodoc:
+module DYI
+  module Shape
 
+    # Base class of all graphical shapes.
+    # @abstract
+    # @since 0.0.0
     class Base < GraphicalElement
+
+      # Returns painting status of the shape.
+      # @attribute painting
+      # @return [Painting] painting status
       attr_painting :painting
+
+      # Returns font status of the shape.
+      # @attribute font
+      # @return [Font] font status
       attr_font :font
-      attr_reader :attributes, :clipping
+
+      # Returns optional attributes of the shape.
+      # @return [Hash] optional attributes
+      attr_reader :attributes
+
+      # Returns clipping status of the shape.
+      # @return [Drawing::Clipping] clipping status
+      attr_reader :clipping
+
+      # Returns a parent element of the shape.
+      # @return [GraphicalElement] a parent element
       attr_reader :parent
+
+      # Returns a location of a reference of a source anchor for the link.
+      # @return [String] a location of a reference
       attr_accessor :anchor_href
-      attr_accessor :anchor_target
 
-      ID_REGEXP = /\A[:A-Z_a-z][0-9:A-Z_a-z]*\z/
+      # Returns a relevant presentation context when the link is activated.
+      # @return [String] a relevant presentation context
+      attr_accessor :anchor_target
 
       # Draws the shape on a parent element.
-      # @param [Element] parent a element that you draw the shape on
-      # @return [Shape::Base] receiver itself
+      # @param [Element] parent a container element on which the shape is drawn
+      # @return [Shape::Base] itself
+      # @raise [ArgumentError] parent is nil
+      # @raise [RuntimeError] this shape already has a parent, or descendants of
+      #   this shape include itself
       def draw_on(parent)
         raise ArgumentError, "parent is nil" if parent.nil?
         return self if @parent == parent
@@ -53,8 +81,7 @@ module DYI #:nodoc:
         self
       end
 
-      # This method is depricated; use Shape::Base#root_element?
-      # @deprecated
+      # @deprecated Use {#root_element?} instead.
       def root_node?
         msg = [__FILE__, __LINE__, ' waring']
         msg << ' DYI::Shape::Base#root_node? is depricated; use DYI::Shape::Base#root_element?'
@@ -62,15 +89,22 @@ module DYI #:nodoc:
         false
       end
 
+      # Returns whether this instance is root element of the shape.
+      # @return [Boolean] always false.
       # @since 1.0.0
       def root_element?
         false
       end
 
+      # Returns transform list.
+      # @return [Array] transform list.
       def transform
         @transform ||= []
       end
 
+      # Translates the shape.
+      # @param [Numeric] x translated value along x-axis
+      # @param [Numeric] y translated value along y-axis
       def translate(x, y=0)
         x = Length.new(x)
         y = Length.new(y)
@@ -85,6 +119,11 @@ module DYI #:nodoc:
         end
       end
 
+      # Scales up (or down) this shape.
+      # @param [Numeric] x scaled ratio along x-axis
+      # @param [Numeric] y scaled ratio along y-axis. If this parameter is nil,
+      #   uses value that equals to parameter `x' value
+      # @param [Coordinate] base_point based coordinate of scaling up (or down)
       def scale(x, y=nil, base_point=Coordinate::ZERO)
         y ||= x
         return if x == 1 && y == 1
@@ -101,6 +140,9 @@ module DYI #:nodoc:
         translate(- base_point.x, - base_point.y) if base_point.nonzero?
       end
 
+      # Rotates this shape.
+      # @param [Numeric] angle rotation angle. specifies degree
+      # @param [Coordinate] base_point based coordinate of rotetion
       def rotate(angle, base_point=Coordinate::ZERO)
         angle %= 360
         return if angle == 0
@@ -116,6 +158,9 @@ module DYI #:nodoc:
         translate(- base_point.x, - base_point.y) if base_point.nonzero?
       end
 
+      # Skews this shape along x-axis.
+      # @param [Numeric] angle skew angle. specifies degree
+      # @param [Coordinate] base_point based coordinate of skew
       def skew_x(angle, base_point=Coordinate::ZERO)
         angle %= 180
         return if angle == 0
@@ -125,6 +170,9 @@ module DYI #:nodoc:
         translate(- base_point.x, - base_point.y) if base_point.nonzero?
       end
 
+      # Skews this shape along y-axis.
+      # @param [Numeric] angle skew angle. specifies degree
+      # @param [Coordinate] base_point based coordinate of skew
       def skew_y(angle, base_point=Coordinate::ZERO)
         angle %= 180
         return if angle == 0
@@ -135,96 +183,102 @@ module DYI #:nodoc:
         translate(- base_point.x, - base_point.y) if base_point.nonzero?
       end
 
+      # Restricts the region to which paint can be applied.
+      # @param [Drawing::Clipping] clipping a clipping object
       def set_clipping(clipping)
         clipping.set_canvas(canvas)
         @clipping = clipping
       end
 
+      # Crears clipping settings.
       def clear_clipping
         @clipping = nil
       end
 
+      # Sets shapes that is used to estrict the region to which paint can be
+      #   applied.
+      # @param [Base] shapes a shape that is used to clip
       def set_clipping_shapes(*shapes)
         set_clipping(Drawing::Clipping.new(*shapes))
       end
 
+      # Returns registed animations.
+      # @return [Array<Animation::Base>] amination list.
       # since 1.0.0
       def animations
         @animations ||= []
       end
 
-      # @return [Boolean] whether the shape is animated
+      # Returns whether the shape is animated.
+      # @return [Boolean] true if the shape is animated, false otherwise
       # @since 1.0.0
       def animate?
         !(@animations.nil? || @animations.empty?)
       end
 
-      # Add animation to the shape
+      # Adds animation to the shape
       # @param [Animation::Base] animation a animation that the shape is run
-      # @return [void]
       # @since 1.0.0
       def add_animation(animation)
         animations << animation
       end
 
-      # Add animation of painting to the shape
-      # @param [Hash] options
+      # Adds animation of painting to the shape
       # @option options [Painting] :from the starting painting of the animation
       # @option options [Painting] :to the ending painting of the animation
       # @option options [Number] :duration a simple duration in seconds
       # @option options [Number] :begin_offset a offset that determine the
-      #                                        animation begin, in seconds
+      #   animation begin, in seconds
       # @option options [Event] :begin_event an event that determine the
-      #                                      animation begin
+      #   animation begin
       # @option options [Number] :end_offset a offset that determine the
-      #                                      animation end, in seconds
-      # @option options [Event] :end_event an event that determine the
-      #                                    animation end
+      #   animation end, in seconds
+      # @option options [Event] :end_event an event that determine the animation
+      #   end
       # @option options [String] :fill `freeze' or `remove'
-      # @return [void]
       # @since 1.0.0
       def add_painting_animation(options)
         add_animation(Animation::PaintingAnimation.new(self, options))
       end
 
-      # Add animation of transform to the shape
-      #
+      # Adds animation of transform to the shape
       # @param [Symbol] type a type of transformation which is to have values
-      # @param [Hash] options
-      # @option options [Number|Array] :from the starting transform of the animation
-      # @option options [Number|Array] :to the ending transform of the animation
+      # @option options [Number, Array] :from the starting transform of the
+      #   animation
+      # @option options [Number, Array] :to the ending transform of the animation
       # @option options [Number] :duration a simple duration in seconds
       # @option options [Number] :begin_offset a offset that determine the
-      #                                        animation begin, in seconds
+      #   animation begin, in seconds
       # @option options [Event] :begin_event an event that determine the
-      #                                      animation begin
+      #   animation begin
       # @option options [Number] :end_offset a offset that determine the
-      #                                      animation end, in seconds
-      # @option options [Event] :end_event an event that determine the
-      #                                    animation end
+      #   animation end, in seconds
+      # @option options [Event] :end_event an event that determine the animation
+      #   end
       # @option options [String] :fill `freeze' or `remove'
-      # @return [void]
       # @since 1.0.0
       def add_transform_animation(type, options)
         add_animation(Animation::TransformAnimation.new(self, type, options))
       end
 
-      # Add animation of painting to the shape
+      # Adds animation of painting to the shape
       # @param [Event] an event that is set to the shape
-      # @return [void]
       # @since 1.0.0
       def set_event(event)
         super
         canvas.set_event(event)
       end
 
+      # Sets a location of a reference of a source anchor for the link.
+      # @param [String] href a location of a reference
       # @since 1.0.0
       def anchor_href=(href)
         anchor_href = href.strip
         @anchor_href = anchor_href.empty? ? nil : anchor_href
       end
 
-      # @return [Boolean] whether the element has a URI reference
+      # Returns whether the element has URI reference.
+      # @return [Boolean] true if the element has URI reference, false otherwise
       # @since 1.0.0
       def has_uri_reference?
         @anchor_href ? true : false
@@ -244,9 +298,28 @@ module DYI #:nodoc:
       end
     end
 
+    # The rectangle in the vector image
+    # @since 0.0.0
     class Rectangle < Base
-      attr_length :width, :height
 
+      # Returns width of the rectangle.
+      # @attribute width
+      # @return [Length] width of the rectangle
+      attr_length :width
+
+      # Returns heigth of the rectangle.
+      # @attribute height
+      # @return [Length] heigth of the rectangle
+      attr_length :height
+
+      # @param [Coordinate] left_top a coordinate of a corner of the rectangle
+      # @param [Length] width width of the rectangle
+      # @param [Length] heigth heigth of the rectangle
+      # @option options [Painting] :painting painting status of the rectangle
+      # @option options [Length] :rx the x-axis radius of the ellipse for
+      #   rounded the rectangle
+      # @option options [Length] :ry the y-axis radius of the ellipse for
+      #   rounded the rectangle
       def initialize(left_top, width, height, options={})
         width = Length.new(width)
         height = Length.new(height)
@@ -258,26 +331,39 @@ module DYI #:nodoc:
         @attributes = init_attributes(options)
       end
 
+      # Returns a x-axis coordinate of the left side of the rectangle.
+      # @return [Length] the x-axis coordinate of the left side
       def left
         @lt_pt.x
       end
 
+      # Returns a x-axis coordinate of the right side of the rectangle.
+      # @return [Length] the x-axis coordinate of the right side
       def right
         @lt_pt.x + width
       end
 
+      # Returns a y-axis coordinate of the top of the rectangle.
+      # @return [Length] a y-axis coordinate of the top
       def top
         @lt_pt.y
       end
 
+      # Returns a y-axis coordinate of the bottom of the rectangle.
+      # @return [Length] a y-axis coordinate of the bottom
       def bottom
         @lt_pt.y + height
       end
 
+      # Returns a coordinate of the center of the rectangle.
+      # @return [Coordinate] a coordinate of the center
       def center
         @lt_pt + Coordinate.new(width.quo(2), height.quo(2))
       end
 
+      # Writes the shape on io object.
+      # @param [Formatter::Base] formatter an object that defines the image format
+      # @param [IO] io an io to be written
       def write_as(formatter, io=$>)
         formatter.write_rectangle(self, io, &(block_given? ? Proc.new : nil))
       end
@@ -286,10 +372,31 @@ module DYI #:nodoc:
 
         public
 
+        # Create a new instance of Rectangle.
+        # @param [Coordinate] left_top a coordinate of a corner of the rectangle
+        # @param [Length] width width of the rectangle
+        # @param [Length] heigth heigth of the rectangle
+        # @option options [Painting] :painting painting status of the rectangle
+        # @option options [Length] :rx the x-axis radius of the ellipse for
+        #   rounded the rectangle
+        # @option options [Length] :ry the y-axis radius of the ellipse for
+        #   rounded the rectangle
+        # @return [Rectangle] a new instance of Rectangle
         def create_on_width_height(left_top, width, height, options={})
           new(left_top, width, height, options)
         end
 
+        # Create a new instance of Rectangle.
+        # @param [Length] top a y-axis coordinate of the top
+        # @param [Length] right a x-axis coordinate of the right side
+        # @param [Length] bottom a y-axis coordinate of the bottom
+        # @param [Length] left a x-axis coordinate of the left side
+        # @option options [Painting] :painting painting status of the rectangle
+        # @option options [Length] :rx the x-axis radius of the ellipse for
+        #   rounded the rectangle
+        # @option options [Length] :ry the y-axis radius of the ellipse for
+        #   rounded the rectangle
+        # @return [Rectangle] a new instance of Rectangle
         def create_on_corner(top, right, bottom, left, options={})
           left_top = Coordinate.new([left, right].min, [top, bottom].min)
           width = (Length.new(right) - Length.new(left)).abs
@@ -299,8 +406,18 @@ module DYI #:nodoc:
       end
     end
 
+    # The circle in the vector image
+    # @since 0.0.0
     class Circle < Base
+
+      # Returns a center coordinate of the circle.
+      # @attribute center
+      # @return [Coordinate]  a center coordinate of the circle
       attr_coordinate :center
+
+      # Returns a radius of the circle.
+      # @attribute radius
+      # @return [Length]  a radius of the circle
       attr_length :radius
 
       def initialize(center, radius, options={})