multiarray 0.11.3 → 0.11.4

data/README.md

@@ -1,3 +1,64 @@
 multiarray
 ==========
+
+**Author**:       Jan Wedekind
+**Copyright**:    2010
+**License**:      GPL
+
+Synopsis
+--------
+
 This Ruby-extension defines the class {Hornetseye::MultiArray} and other native datatypes. {Hornetseye::MultiArray} provides multi-dimensional Ruby arrays with elements of same type. The extension is designed to be mostly compatible with Masahiro Tanaka's NArray. However it allows the definition of custom element types and operations on them. This work was also inspired by Ronald Garcia's boost::multi_array and by Todd Veldhuizen's Blitz++.
+
+Installation
+------------
+
+To install this Ruby extension, use the following command:
+
+    $ sudo gem install multiarray
+
+Alternatively you can install the Ruby extension from source as follows:
+
+    $ sudo rake install
+
+Usage
+-----
+
+Simply run Interactive Ruby:
+
+    $ irb
+
+You can load the Ruby extension as shown below. The example shows a few array operations and their results.
+
+    require 'rubygems'
+    require 'multiarray'
+    include Hornetseye
+    m = MultiArray[ [ 2, 3 ], [ 4, 5 ] ]
+    # MultiArray(UBYTE,2,2):
+    # [ [ 2, 3 ],
+    #   [ 4, 5 ] ]
+    m[ 1, 0 ]
+    # 3
+    m[ 0 ][ 1 ]
+    # 3
+    m + 1
+    # MultiArray(UBYTE,2,2):
+    # [ [ 3, 4 ],
+    #   [ 5, 6 ] ]
+    1.0 / m
+    # MultiArray(DFLOAT,2,2):
+    # [ [ 0.5, 0.3333333333333333 ],
+    #   [ 0.25, 0.2 ] ]
+    m[ 1 ]
+    # Sequence(UBYTE,2):
+    # [ 4, 5 ]
+    sum { |i,j| m[i,j] }
+    # 14
+    sum { |j| m[j] }
+    # Sequence(UBYTE,2):
+    # [ 6, 8 ]
+    -m.to_byte
+    # MultiArray(BYTE,2,2):
+    # [ [ -2, -3 ],
+    #   [ -4, -5 ] ]
+    

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/packagetask'
 require 'rbconfig'
 
 PKG_NAME = 'multiarray'
-PKG_VERSION = '0.11.3'
+PKG_VERSION = '0.11.4'
 RB_FILES = FileList[ 'lib/**/*.rb' ]
 TC_FILES = FileList[ 'test/tc_*.rb' ]
 TS_FILES = FileList[ 'test/ts_*.rb' ]

data/lib/multiarray.rb

@@ -75,6 +75,10 @@ class Object
 
     # Object#instance_exec is defined if it does not exist already
     #
+    # @param [Array<Object>] arguments The arguments to pass to the block.
+    # @param [Proc] block The block to be executed in the object's environment.
+    # @return [Object] The result of executing the block.
+    # 
     # @private
     def instance_exec( *arguments, &block )
       block.bind( self )[ *arguments ]
@@ -310,6 +314,9 @@ class Fixnum
 
   # +&+ is modified to work with this library
   #
+  # @param [Object] other Second operand for binary +and+ operation.
+  # @return [Object] Result of binary operation.
+  #
   # @private
   def intand_with_hornetseye( other )
     if other.is_a? Integer
@@ -324,6 +331,9 @@ class Fixnum
 
   # +|+ is modified to work with this library
   #
+  # @param [Object] other Second operand for binary +or+ operation.
+  # @return [Object] Result of binary operation.
+  #
   # @private
   def intor_with_hornetseye( other )
     if other.is_a? Integer
@@ -338,6 +348,9 @@ class Fixnum
 
   # +^+ is modified to work with this library
   #
+  # @param [Object] other Second operand for binary +xor+ operation.
+  # @return [Object] Result of binary operation.
+  #
   # @private
   def intxor_with_hornetseye( other )
     if other.is_a? Integer
@@ -352,6 +365,9 @@ class Fixnum
 
   # +<<+ is modified to work with this library
   #
+  # @param [Object] other Second operand for binary +shl+ operation.
+  # @return [Object] Result of binary operation.
+  #
   # @private
   def shl_with_hornetseye( other )
     if other.is_a? Integer
@@ -366,6 +382,9 @@ class Fixnum
 
   # +>>+ is modified to work with this library
   #
+  # @param [Object] other Second operand for binary +shr+ operation.
+  # @return [Object] Result of binary operation.
+  #
   # @private
   def shr_with_hornetseye( other )
     if other.is_a? Integer
@@ -380,6 +399,12 @@ class Fixnum
 
   if method_defined? :rpower
 
+    # +**+ is modified to work with this library
+    #
+    # @param [Object] other Second operand for binary operation.
+    # @return [Object] Result of binary operation.
+    #
+    # @private
     def power_with_hornetseye( other )
       if other.is_a? Hornetseye::Node
         x, y = other.coerce self
@@ -437,6 +462,7 @@ class Range
 
 end
 
+# The +Numeric+ class is extended with a few methods
 class Numeric
 
   # Compute complex conjugate
@@ -497,6 +523,7 @@ class Numeric
 
 end
 
+# The +Array+ class is extended
 class Array
 
   # Element-wise operation based on element and its index
@@ -516,6 +543,7 @@ require 'complex'
 require 'malloc'
 require 'rbconfig'
 require 'set'
+require 'thread'
 require 'tmpdir'
 require 'multiarray/malloc'
 require 'multiarray/list'

data/lib/multiarray/complex.rb

@@ -17,11 +17,14 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # When compiling operations this class replaces +Complex+
+  #
+  # @private
   class InternalComplex
 
     class << self
 
-      # Check compatibility of other type.
+      # Check compatibility of other type
       #
       # This method checks whether binary operations with the other Ruby object can
       # be performed without requiring coercion.
@@ -30,30 +33,58 @@ module Hornetseye
       #
       # @return [Boolean] Returns +false+ if Ruby object requires
       #         coercion.
+      #
+      # @private
       def generic?( value )
         value.is_a?( Numeric ) or value.is_a?( GCCValue )
       end
 
+      # Construct complex number using polar coordinates
+      #
+      # @param [GCCValue,Numeric] r Radius or complex modulus.
+      # @param [GCCValue,Numeric] theta Angle or complex argument. 
+      #
+      # @return [InternalComplex] The specified complex number.
+      #
+      # @private
       def polar( r, theta )
         new r * Math.cos( theta ), r * Math.sin( theta )
       end
 
     end
 
-    attr_accessor :real, :imag
+    # Get real component of complex number
+    #
+    # @return [GCCValue,Numeric] The real component.
+    #
+    # @private
+    attr_accessor :real
 
+    # Get imaginary component of complex number
+    #
+    # @return [GCCValue,Numeric] The imaginary component.
+    #
+    # @private
+    attr_accessor :imag
+
+    # Constructor for complex number
+    #
+    # @param [GCCValue,Numeric] real The real component.
+    # @param [GCCValue,Numeric] imag The imaginary component.
+    #
+    # @return [InternalComplex] The complex number.
     def initialize( real, imag )
       @real, @imag = real, imag
     end
 
-    # Return string with information about this object.
+    # Return string with information about this object
     #
     # @return [String] Returns a string (e.g. "InternalComplex(1,2)").
     def inspect
       "InternalComplex(#{@real.inspect},#{@imag.inspect})"
     end
 
-    # Return string with information about this object.
+    # Return string with information about this object
     #
     # @return [String] Returns a string (e.g. "InternalComplex(1,2)").
     def to_s
@@ -71,6 +102,13 @@ module Hornetseye
       @real, @imag = value.real, value.imag
     end
 
+    # Coerce with other object
+    #
+    # @param [InternalComplex,Object] other Other object.
+    #
+    # @return [Array<InternalComplex>] Result of coercion.
+    #
+    # @private
     def coerce( other )
       if other.is_a? InternalComplex
         return other, self
@@ -81,30 +119,67 @@ module Hornetseye
       end
     end
 
+    # Compute complex conjugate
+    #
+    # @return [InternalComplex] The result.
+    #
+    # @private
     def conj
       InternalComplex.new @real, -@imag
     end
 
+    # Compute complex modulus
+    #
+    # @return [InternalComplex] The result.
+    #
+    # @private
     def abs
       Math.hypot @real, @imag
     end
 
+    # Compute complex argument
+    #
+    # @return [InternalComplex] The result.
+    #
+    # @private
     def arg
       Math.atan2 @imag, @real
     end
 
+    # Compute polar coordinates
+    #
+    # @return [Array<Object>] Returns complex modulus and argument.
+    #
+    # @private
     def polar
       return abs, arg
     end
 
+    # This operation has no effect
+    #
+    # @return [InternalComplex] Returns +self+.
+    #
+    # @private
     def +@
       self
     end
 
+    # Negate complex value
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def -@
       InternalComplex.new -@real, -@imag
     end
 
+    # Add complex values
+    #
+    # @param [Object] Second operand for binary operation.
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def +( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         InternalComplex.new @real + other.real, @imag + other.imag
@@ -116,6 +191,13 @@ module Hornetseye
       end
     end
 
+    # Subtract complex values
+    #
+    # @param [Object] Second operand for binary operation.
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def -( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         InternalComplex.new @real - other.real, @imag - other.imag
@@ -127,6 +209,13 @@ module Hornetseye
       end
     end
 
+    # Multiply complex values
+    #
+    # @param [Object] Second operand for binary operation.
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def *( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         InternalComplex.new @real * other.real - @imag * other.imag,
@@ -139,6 +228,13 @@ module Hornetseye
       end
     end
 
+    # Divide complex values
+    #
+    # @param [Object] Second operand for binary operation.
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def /( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         self * other.conj / other.abs2
@@ -150,6 +246,14 @@ module Hornetseye
       end
     end
 
+    
+    # Complex exponentiation
+    #
+    # @param [Object] Second operand for binary operation.
+    #
+    # @return [InternalComplex] The result
+    #
+    # @private
     def **( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         r, theta = polar
@@ -167,14 +271,29 @@ module Hornetseye
       end
     end
 
+    # Check whether value is equal to zero
+    #
+    # @return [Boolean,GCCValue] The result.
+    #
+    # @private
     def zero?
       @real.zero?.and @imag.zero?
     end
 
+    # Check whether value is not equal to zero
+    #
+    # @return [Boolean,GCCValue] The result.
+    #
+    # @private
     def nonzero?
       @real.nonzero?.or @imag.nonzero?
     end
 
+    # Compute square of complex modulus
+    #
+    # @return [Numeric,GCCValue] The result.
+    #
+    # @private
     def abs2
       @real * @real + @imag * @imag
     end
@@ -185,6 +304,8 @@ module Hornetseye
     #
     # @return [Boolean] Returns boolean indicating whether objects are
     #         equal or not.
+    #
+    # @private
     def ==( other )
       if other.is_a?( InternalComplex ) or other.is_a?( Complex )
         @real.eq( other.real ).and( @imag.eq( other.imag ) )
@@ -197,10 +318,11 @@ module Hornetseye
 
     # Decompose complex number
     #
-    # This method decomposes the complex number into an array.
+    # This method decomposes the complex number.
     #
-    # @return [Node] Returns an array with the real and imaginary component as
-    #         elements.
+    # @return [Numeric,GCCValue] Returns the requested component.
+    #
+    # @private
     def decompose( i )
       [ @real, @imag ][ i ]
     end
@@ -209,8 +331,16 @@ module Hornetseye
 
 end
 
+# The +Math+ module is extended with a few methods
 module Math
 
+  # Square root for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def sqrt_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = sqrt( ( z.abs + z.real ) / 2 )
@@ -226,6 +356,13 @@ module Math
   module_function :sqrt_without_internalcomplex
   module_function :sqrt
 
+  # Exponent for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def exp_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = exp( z.real ) * cos( z.imag )
@@ -240,6 +377,13 @@ module Math
   module_function :exp_without_internalcomplex
   module_function :exp
 
+  # Cosinus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def cos_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = cos( z.real ) * cosh( z.imag )
@@ -254,6 +398,13 @@ module Math
   module_function :cos_without_internalcomplex
   module_function :cos
 
+  # Sinus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def sin_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = sin( z.real ) * cosh( z.imag )
@@ -268,6 +419,13 @@ module Math
   module_function :sin_without_internalcomplex
   module_function :sin
 
+  # Tangens for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def tan_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       sin( z ) / cos( z )
@@ -280,6 +438,13 @@ module Math
   module_function :tan_without_internalcomplex
   module_function :tan
 
+  # Cosinus hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def cosh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = cosh( z.real ) * cos( z.imag )
@@ -294,6 +459,13 @@ module Math
   module_function :cosh_without_internalcomplex
   module_function :cosh
 
+  # Sinus hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def sinh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       real = sinh( z.real ) * cos( z.imag )
@@ -308,6 +480,13 @@ module Math
   module_function :sinh_without_internalcomplex
   module_function :sinh
 
+  # Tangens hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def tanh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       sinh( z ) / cosh( z )
@@ -320,6 +499,13 @@ module Math
   module_function :tanh_without_internalcomplex
   module_function :tanh
 
+  # Logarithm for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def log_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       r, theta = z.polar
@@ -333,6 +519,13 @@ module Math
   module_function :log_without_internalcomplex
   module_function :log
 
+  # Base-10 logarithm for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def log10_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       log( z ) / log( 10 )
@@ -345,6 +538,13 @@ module Math
   module_function :log10_without_internalcomplex
   module_function :log10
 
+  # Arcus cosinus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def acos_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       -1.0.im * log( z + 1.0.im * sqrt( 1.0 - z * z ) )
@@ -357,6 +557,13 @@ module Math
   module_function :acos_without_internalcomplex
   module_function :acos
 
+  # Arcus sinus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def asin_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       -1.0.im * log( 1.0.im * z + sqrt( 1.0 - z * z ) )
@@ -369,6 +576,13 @@ module Math
   module_function :asin_without_internalcomplex
   module_function :asin
 
+  # Arcus tangens for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def atan_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       1.0.im * log( ( 1.0.im + z ) / ( 1.0.im - z ) ) / 2.0
@@ -381,6 +595,13 @@ module Math
   module_function :atan_without_internalcomplex
   module_function :atan
 
+  # Arcus cosinus hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def acosh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       log( z + sqrt( z * z - 1.0 ) )
@@ -393,6 +614,13 @@ module Math
   module_function :acosh_without_internalcomplex
   module_function :acosh
 
+  # Arcus sinus hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def asinh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       log( z + sqrt( 1.0 + z * z ) )
@@ -405,6 +633,13 @@ module Math
   module_function :asinh_without_internalcomplex
   module_function :asinh
 
+  # Arcus tangens hyperbolicus for internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def atanh_with_internalcomplex( z )
     if z.is_a? Hornetseye::InternalComplex
       log( ( 1.0 + z ) / ( 1.0 - z ) ) / 2.0
@@ -417,6 +652,13 @@ module Math
   module_function :atanh_without_internalcomplex
   module_function :atanh
 
+  # Arcus tangens of two internal complex numbers
+  #
+  # @param [Object,Hornetseye::InternalComplex] z Parameter for unary method.
+  #
+  # @return [Object,Hornetseye::InternalComplex] Result of method call.
+  #
+  # @private
   def atan2_with_internalcomplex( y, x )
     if [ x, y ].any? { |v| v.is_a? Hornetseye::InternalComplex }
       -1.0.im * log( ( x + 1.0.im * y ) / sqrt( x * x + y * y ) )
@@ -433,6 +675,7 @@ end
 
 module Hornetseye
 
+  # Class for representing native complex values
   class COMPLEX_ < Composite
 
     class << self
@@ -440,6 +683,12 @@ module Hornetseye
       # Set base class attribute
       #
       # Sets number of elements to two.
+      #
+      # @param [Class] subclass The class inheriting from +COMPLEX_+.
+      #
+      # @return The return value should be ignored.
+      #
+      # @private
       def inherited( subclass )
         subclass.num_elements = 2
       end
@@ -474,15 +723,23 @@ module Hornetseye
         end
       end
 
+      # Identifier array used internally
+      #
+      # @private
+      IDENTIFIER = { SFLOAT => 'SCOMPLEX',
+                     DFLOAT => 'DCOMPLEX' }
+
       # Display information about this class
       #
       # @return [String] Returns string with information about this class (e.g.
       #         "SCOMPLEX").
       def inspect
         unless element_type.nil?
-          { SFLOAT => 'SCOMPLEX',
-            DFLOAT => 'DCOMPLEX' }[ element_type ] ||
-          "COMPLEX(#{element_type.inspect})"
+          retval = IDENTIFIER[ element_type ] || "COMPLEX(#{element_type.inspect})"
+          ( class << self; self; end ).instance_eval do
+            define_method( :inspect ) { retval }
+          end
+          retval
         else
           super
         end
@@ -550,7 +807,7 @@ module Hornetseye
           element_type == other.element_type
       end
 
-      # Compute hash value for this class.
+      # Compute hash value for this class
       #
       # @return [Fixnum] Hash value
       #
@@ -572,6 +829,9 @@ module Hornetseye
 
     end
 
+    # Constructor for native complex number
+    #
+    # @param [Complex,InternalComplex] value Complex number.
     def initialize( value = self.class.default )
       if Thread.current[ :function ].nil? or
         [ value.real, value.imag ].all? { |c| c.is_a? GCCValue }
@@ -630,6 +890,11 @@ module Hornetseye
       [ @value.real, @value.imag ]
     end
 
+    # Namespace containing method for matching elements of type COMPLEX_
+    #
+    # @see COMPLEX_
+    #
+    # @private
     module Match
 
       # Method for matching elements of type COMPLEX_
@@ -674,6 +939,8 @@ module Hornetseye
       #
       # @param [Class] context Other type to align with.
       #
+      # @return [Class] Result of type alignment.
+      #
       # @private
       def align( context )
         if self < COMPLEX_
@@ -689,11 +956,15 @@ module Hornetseye
 
   end
 
+  # Module providing the operations to manipulate array expressions
   module Operations
 
     define_unary_op :real, :scalar
     define_unary_op :imag, :scalar
 
+    # Fast extraction for real values of complex array
+    #
+    # @return [Node] Array with real values.
     def real_with_decompose
       if typecode == OBJECT or is_a?( Variable )
         real_without_decompose
@@ -706,6 +977,11 @@ module Hornetseye
 
     alias_method_chain :real, :decompose
 
+    # Assignment for real values of complex array
+    #
+    # @param [Object] Value or array of values to assign to real components.
+    #
+    # @return [Object] Returns +value+.
     def real=( value )
       if typecode < COMPLEX_
         decompose( 0 )[] = value
@@ -718,6 +994,9 @@ module Hornetseye
       end
     end
 
+    # Fast extraction of imaginary values of complex array
+    #
+    # @return [Node] Array with imaginary values.
     def imag_with_decompose
       if typecode == OBJECT or is_a?( Variable )
         imag_without_decompose
@@ -730,6 +1009,11 @@ module Hornetseye
 
     alias_method_chain :imag, :decompose
 
+    # Assignment for imaginary values of complex array
+    #
+    # @param [Object] Value or array of values to assign to imaginary components.
+    #
+    # @return [Object] Returns +value+.
     def imag=( value )
       if typecode < COMPLEX_
         decompose( 1 )[] = value
@@ -744,16 +1028,29 @@ module Hornetseye
 
   end
 
-  def COMPLEX( arg )
+  # Create a class deriving from +COMPLEX_+
+  #
+  # Create a class deriving from +COMPLEX_+. The parameter +element_type+ is assigned
+  # to the corresponding attribute of the resulting class.
+  #
+  # @param [Class] element_type The native type of the complex components.
+  #
+  # @return [Class] A class deriving from +COMPLEX_+.
+  #
+  # @see COMPLEX_
+  # @see COMPLEX_.element_type
+  def COMPLEX( element_type )
     retval = Class.new COMPLEX_
-    retval.element_type = arg
+    retval.element_type = element_type
     retval
   end
 
   module_function :COMPLEX
 
+  # Convenience shortcut for single-precision floating-point complex numbers
   SCOMPLEX = COMPLEX SFLOAT
 
+  # Convenience shortcut for double-precision floating-point complex numbers
   DCOMPLEX = COMPLEX DFLOAT
 
   # Shortcut for constructor