dyi 1.1.1 → 1.1.2

data/lib/dyi/matrix.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,8 +19,10 @@
 # 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 DYI
 
+  # @since 1.0.0
   class Matrix
     attr_accessor :xx, :yx, :xy, :yy, :x0, :y0
 

data/lib/dyi/painting.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,60 +19,127 @@
 # 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 DYI
 
+  # +Painting+ is used to specify how the drawing of the interior and the
+  # outline of the shape. {Shape::Base} objects (or objects of its subclass)
+  # have +painting+ attribute whose value is instance of this class.
+  # @since 0.0.0
   class Painting
-    IMPLEMENT_ATTRIBUTES = [:opacity,:fill,:fill_opacity,:fill_rule,:stroke,:stroke_dasharray,:stroke_dashoffset,:stroke_linecap,:stroke_linejoin,:stroke_miterlimit,:stroke_opacity,:stroke_width,:display,:visibility]
-    VALID_VALUES = {
-      :fill_rule => ['nonzero','evenodd'],
-      :stroke_linecap => ['butt','round','square'],
-      :stroke_linejoin => ['miter','round','bevel'],
-      :display => ['block','none'],
-      :visibility => ['visible','hidden']
-    }
-
-    ##
-    # :method: fill
-
-    ##
-    # :method: fill_opacity
-
-    ##
-    # :method: fill_rule
-
-    ##
-    # :method: stroke
-
-    ##
-    # :method: stroke_dasharray
-
-    ##
-    # :method: stroke_dashoffset
-
-    ##
-    # :method: stroke_linecap
 
-    ##
-    # :method: stroke_linejoin
-
-    ##
-    # :method: stroke_miterlimit
-
-    ##
-    # :method: stroke_opacity
-
-    ##
-    # :method: stroke_width
-
-    ##
-    # :method: display
-
-    ##
-    # :method: visibility
-
-    ##
+    # @private
+    IMPLEMENT_ATTRIBUTES = [:opacity, :fill, :fill_opacity, :fill_rule,
+                            :stroke, :stroke_dasharray, :stroke_dashoffset,
+                            :stroke_linecap, :stroke_linejoin, :stroke_miterlimit,
+                            :stroke_opacity, :stroke_width,
+                            :display, :visibility]
+    # @private
+    VALID_VALUES = {:fill_rule => ['nonzero','evenodd'],
+                    :stroke_linecap => ['butt','round','square'],
+                    :stroke_linejoin => ['miter','round','bevel'],
+                    :display => ['block','none'],
+                    :visibility => ['visible','hidden']}
+
+    # @attribute opacity
+    # Returns or sets opacity of the paiting operation. Opacity of Both +stroke+
+    # and +fill+ is set at the same time by this attribute.
+    # @return [Float] the value of attribute opacity
+    # @since 1.0.0
+    #+++
+    # @attribute fill
+    # Returns or sets the interior painting of the shape.
+    # @return [Color, #write_as] the value of attribute fill
+    #+++
+    # @attribute fill_opacity
+    # Returns or sets the opacity of the paiting operation used to paint the
+    # interior of the shape.
+    # @return [Float] the value of attribute fill_opacity
+    #+++
+    # @attribute fill_rule
+    # Returns or sets the rule which is to be used to detemine what parts of the
+    # canvas are included inside the shape. specifies one of the following
+    # values: <tt>"nonzero"</tt>, <tt>"evenodd"</tt>
+    # @return [String] the value of attribute fill_rule
+    #+++
+    # @attribute stroke
+    # Returns or sets the painting along the outline of the shape.
+    # @return [Color, #write_as] the value of attribute stroke
+    #+++
+    # @attribute stroke_dasharray
+    # Returns or sets the pattern of dashes and gaps used to stroke paths.
+    # @return [Array<Length>] the value of attribute stroke_dasharray
+    #+++
+    # @attribute stroke_dashoffset
+    # Returns or sets the distance into the dash pattern to start the dash.
+    # @return [Length] the value of attribute stroke_dashoffset
+    #+++
+    # @attribute stroke_linecap
+    # Returns or sets the shape to be used at the end of open subpaths when they
+    # are stroked. specifies one of the following values: <tt>"butt"</tt>,
+    # <tt>"round"</tt>, <tt>"square"</tt>
+    # @return [String] the value of attribute stroke_linecap
+    #+++
+    # @attribute stroke_linejoin
+    # Returns or sets the shape to be used at the corners of paths or basic
+    # shapes when they are stroked. specifies one of the following vlaues:
+    # <tt>"miter"</tt>, <tt>"round"</tt>, <tt>"bevel"</tt>
+    # @return [String] the value of attribute stroke_linejoin
+    #+++
+    # @attribute stroke_miterlimit
+    # Returns or sets the limit value on the ratio of the miter length to the
+    # value of +stroke_width+ attribute. When the ratio exceeds this attribute
+    # value, the join is converted from a _miter_ to a _bevel_.
+    # @return [Float] the value of attribute stroke_mitterlimit
+    #+++
+    # @attribute stroke_opacity
+    # Returns or sets the opacity of the painting operation used to stroke.
+    # @return [Float] the value of attribute stroke_opacity
+    #+++
+    # @attribute stroke_width
+    # Returns or sets the width of the stroke.
+    # @return [Length] the value of attribute stroke_width
+    #+++
+    # @attribute display
+    # Returns or sets whether the shape is displayed. specifies one of the
+    # following vlaues: <tt>"block"</tt>, <tt>"none"</tt>
+    # @return [String] the value of attribute display
+    #+++
+    # @attribute visibility
+    # Returns or sets whether the shape is hidden. specifies one of the
+    # following vlaues: <tt>"visible"</tt>, <tt>"hidden"</tt>
+    # @return [String] the value of attribute visibility
     attr_reader *IMPLEMENT_ATTRIBUTES
 
+    # Creates and returns a new instace of Paintng. If the argutment is a
+    # instance of Painting, returns a copy of the argument.
+    # @option options [String] :display the value of attribute {#display display};
+    #   one of following values: <tt>"block"</tt>, <tt>"none"</tt>
+    # @option options [Color, #write_as] :fill the value of attribute {#fill fill}
+    # @option options [#to_f] :fill_opacity the value of attribute fill_opacity
+    # @option options [String] :fill_rule the value of attribute {#fill_rule
+    #   fill_rule}; one of following values: <tt>"nonzero"</tt>, <tt>"evenodd"</tt>
+    # @option options [#to_f] :opacity the value of attribute {#opacity opacity}
+    # @option options [Color, #write_as] :stroke the value of attribute {#stroke
+    #   stroke}
+    # @option options [Array<Length>, String] :stroke_dasharray the value of
+    #   attribute {#stroke_dasharray stroke_dasharray}
+    # @option options [Length] :stroke_dashoffset the value of attribute
+    #   {#stroke_dashoffset stroke_dashoffset}
+    # @option options [String] :stroke_linecap the value of attribute
+    #   {#stroke_linecap stroke_linecap}; one of following values:
+    #   <tt>"butt"</tt>, <tt>"round"</tt>, <tt>"square"</tt>
+    # @option options [String] :stroke_linejoin the value of attribute
+    #   {#stroke_linejoin stroke_linejoin}; one of following values:
+    #   <tt>"miter"</tt>, <tt>"round"</tt>, <tt>"bevel"</tt>
+    # @option options [#to_f] :stroke_miterlimit the value of attribute
+    #   {#stroke_miterlimit stroke_miterlimit}
+    # @option options [#to_f] :stroke_opacity the value of attribute
+    #   {#stroke_opacity stroke_opacity}
+    # @option options [Length] :stroke_width the value of attribute
+    #   {#stroke_width stroke_width}
+    # @option options [String] :visible the value of attribute {#visibility
+    #   visibility}; one of following values: <tt>"visible"</tt>, <tt>"hidden"</tt>
     def initialize(options={})
       case options
       when Painting
@@ -88,42 +155,20 @@ module DYI #:nodoc:
       end
     end
 
-    ##
-    # :method: fill_rule=
-    # 
-    # :call-seq:
-    # fill_rule= (value)
-    # 
-
-    ##
-    # :method: stroke_linecap=
-    # 
-    # :call-seq:
-    # stroke_linecap= (value)
-    # 
-
-    ##
-    # :method: stroke_linejoin=
-    # 
-    # :call-seq:
-    # stroke_linejoin= (value)
-    # 
-
-    ##
-    # :method: display=
-    # 
-    # :call-seq:
-    # display= (value)
-    # 
-
-    ##
-    # :method: visibility=
-    # 
-    # :call-seq:
-    # visibility= (value)
-    # 
-
-    ##
+    # @attribute [w] fill_rule
+    # @param [String] value the value of attribute fill_rule
+    #+++
+    # @attribute [w] stroke_linecap
+    # @param [String] value the value of attribute stroke_linecap
+    #+++
+    # @attribute [w] stroke_linejoin
+    # @param [String] value the value of attribute stroke_linejoin
+    #+++
+    # @attribute [w] display
+    # @param [String] value the value of attribute display
+    #+++
+    # @attribute [w] visibility
+    # @param [String] value the value of attribute visibility
     VALID_VALUES.each do |attr, valid_values|
       define_method("#{attr.to_s}=") {|value|
         if (value = value.to_s).size == 0
@@ -135,35 +180,51 @@ module DYI #:nodoc:
       }
     end
 
+    # @attribute
+    # @param [Color, #write_as] color the value of attribute fill
     def fill=(color)
       @fill = color.respond_to?(:color?) && color.color? ? color : Color.new_or_nil(color)
     end
 
+    # @attribute
+    # @param [Color, #write_as] color the value of attribute stroke
     def stroke=(color)
       @stroke = color.respond_to?(:color?) && color.color? ? color : Color.new_or_nil(color)
     end
 
+    # @attribute
+    # @param [Float] opacity the value of attribute opacity
     # @since 1.0.0
     def opacity=(opacity)
       @opacity = opacity.nil? ? nil : opacity.to_f
     end
 
+    # @attribute
+    # @param [Float] opacity the value of attribute fill_opacity
     def fill_opacity=(opacity)
       @fill_opacity = opacity.nil? ? nil : opacity.to_f
     end
 
+    # @attribute
+    # @param [Float] opacity the value of attribute stroke_opacity
     def stroke_opacity=(opacity)
       @stroke_opacity = opacity.nil? ? nil : opacity.to_f
     end
 
+    # @attribute
+    # @param [Length] width the value of attribute stroke_width
     def stroke_width=(width)
       @stroke_width = Length.new_or_nil(width)
     end
 
+    # @attribute
+    # @param [Float] miterlimit the value of attribute stroke_miterlimit
     def stroke_miterlimit=(miterlimit)
       @stroke_miterlimit = miterlimit.nil? ? nil : [miterlimit.to_f, 1].max
     end
 
+    # @attribute
+    # @param [Array<Legth>, String] array the value of attribute stroke_dasharray
     def stroke_dasharray=(array)
       if (array.nil? || array.empty?)
         @stroke_dasharray = nil
@@ -174,20 +235,28 @@ module DYI #:nodoc:
       end
     end
 
+    # @attribute
+    # @param [Length] offset the value of attribute stroke_dashoffset
     def stroke_dashoffset=(offset)
       @stroke_dashoffset = Length.new_or_nil(offset)
     end
 
+    # Returns the hash of the attribute values. Even if the return value of this
+    # method is modified, the attribute value of the object is not modify.
+    # @return [Hash{Symbol => Object}] the copy of the attribute values
     def attributes
       IMPLEMENT_ATTRIBUTES.inject({}) do |hash, attr|
         value = instance_variable_get("@#{attr}")
         unless value.nil?
-          hash[attr] = value # value.respond_to?(:join) ? value.join(',') : value.to_s
+          hash[attr] = value
         end
         hash
       end
     end
 
+    # Returns whether a value has been set some attribute in this object.
+    # @return [Boolean] true if a value has been set some attribute in this
+    #   object, false otherwise
     def empty?
       IMPLEMENT_ATTRIBUTES.all? do |attr|
         not instance_variable_get("@#{attr}")
@@ -196,6 +265,11 @@ module DYI #:nodoc:
 
     class << self
 
+      # Returns a new instace of +Painting+ if the argments is not +nil+ (calls
+      # +Painting.new+ method), but returns +nil+ if the argument is +nil+.
+      # @return [Painting, nil] a new instace of Painting if the argments is not
+      #   nil, nil otherwise
+      # @see #initialize
       def new_or_nil(*args)
         (args.size == 1 && args.first.nil?) ? nil : new(*args)
       end

data/lib/dyi/script.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
 #

data/lib/dyi/script/ecmascript.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,25 +18,21 @@
 #
 # 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 classes of client side scripting.  The script becomes
-# effective only when it is output by SVG format.
-#
-# @since 1.0.0
 
+#
 module DYI
   module Script
+
     # Module for using ECMAScript.  The script generated by this module comfirms
     # to ECMAScript 5.1 (Ecma International Standard ECMA-262).
+    # @since 1.0.0
     module EcmaScript
 
       # 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
+      # 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
@@ -50,37 +46,22 @@ module DYI
       # 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
+      # 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
 
+        # @function
         def get_element(element)
           parts = []
           parts << 'document.getElementById("' << (element.respond_to?(:publish_id) ? element.id : element) << '")'
           parts.join
         end
 
+        # @function
         def add_event_listener(event, listener)
           parts = []
           parts << get_element(event.target)
@@ -91,6 +72,7 @@ module DYI
           parts.join
         end
 
+        # @function
         def dispatch_evnet(event)
           parts = []
           parts << get_element(event.target)
@@ -100,8 +82,8 @@ module DYI
 
         # Returns an ECMAScript value of a metadata that this image has.
         # @return [String] a string that means 
+        # @function
         # @since 1.1.1
-        # @api function
         def metadata_parse_json
 =begin
 script =<<-EOS
@@ -130,10 +112,12 @@ EOS
         # element
         # @param [String|Symbol] attribute_name the name of attribute
         # @return [String] ECMAScript string
+        # @function
         # @example
         #   rect = pen.draw_rectange(canvas, [0, 0], 20, 30, :id => "rect1")
         #   get_attribute(rect, "width")
         #        # => "document.getElementById(\"rect1\").getAttribute(\"width\")"
+        # @function
         # @since 1.1.0
         def get_attribute(element, attribute_name)
           "#{get_element(element)}.getAttribute(\"#{attribute_name}\")"
@@ -147,8 +131,9 @@ EOS
         # @return [String] ECMAScript string
         # @example
         #   rect = pen.draw_rectange(canvas, [0, 0], 20, 30, :id => "rect1")
-        #   get_attribute(rect, "width", 50)
+        #   set_attribute(rect, "width", 50)
         #        # => "document.getElementById(\"rect1\").setAttribute(\"x\",\"50\")"
+        # @function
         # @since 1.1.0
         def set_attribute(element, attribute_name, value)
           "#{get_element(element)}.setAttribute(\"#{attribute_name}\",\"#{value.to_s}\")"
@@ -159,6 +144,7 @@ EOS
         # @param [Shape::Text] text_element the target element
         # @param [String] text new contents of the text element
         # @return [String] ECMAScript string
+        # @function
         # @since 1.1.0
         def rewrite_text(text_element, text)
           lines = text.split(/(?:\r\n|\n|\r)/).map{|line| to_ecmascript_string(line)}
@@ -188,6 +174,7 @@ EOS
         #       #=> "\"This figure is made using \\\"DYI\\\".\""
         #   to_ecmascript_string("\346\227\245\346\234\254\350\252\236")
         #       #=> "\"\\u65E5\\u672C\\u8A9E\""  (encoding: utf-8)
+        # @function
         # @since 1.1.0
         def to_ecmascript_string(obj)
           chars = []
@@ -210,6 +197,7 @@ EOS
           chars.join
         end
 
+        # @function
         def draw_text_border(*elements)
           elements_js_variable = []
           elements_js_variable << "var a=["
@@ -265,6 +253,7 @@ EOS
           "(function(){#{elements_js_variable.join}for(var b=0;b<#{elements.size};b++){var c=a[b];var d=null,right=null,bottom=null,left=null,rect=null;for(var e=0,len=c.a.childNodes.length;e<len;e++){var f=c.a.childNodes.item(e);if(f.localName==\"text\"){var g=f.getComputedTextLength();if(f.getNumberOfChars()>0){var h=f.getExtentOfChar(0);if(d==null||h.y<d)d=h.y;if(right==null||right<h.x+g)right=h.x+g;if(bottom==null||bottom<h.y+h.height)bottom=h.y+h.height;if(left==null||h.x<left)left=h.x;}}else if(f.localName==\"rect\")rect=f;}rect.setAttribute(\"x\",left-c.b);rect.setAttribute(\"y\",d-c.c);rect.setAttribute(\"width\",right-left+c.b*2);rect.setAttribute(\"height\",bottom-d+c.c*2);}})();"
         end
 
+        # @function
         def form_legend_labels(legend)
 =begin
 script =<<-EOS