nmatrix 0.0.3 → 0.0.4

data/lib/nmatrix/shortcuts.rb

@@ -1,3 +1,4 @@
+#--
 # = NMatrix
 #
 # A linear algebra library for scientific computation in Ruby.
@@ -8,8 +9,8 @@
 #
 # == Copyright Information
 #
-# SciRuby is Copyright (c) 2010 - 2012, Ruby Science Foundation
-# NMatrix is Copyright (c) 2012, Ruby Science Foundation
+# SciRuby is Copyright (c) 2010 - 2013, Ruby Science Foundation
+# NMatrix is Copyright (c) 2013, Ruby Science Foundation
 #
 # Please see LICENSE.txt for additional copyright notices.
 #
@@ -23,30 +24,43 @@
 # == shortcuts.rb
 #
 # These are shortcuts for NMatrix and NVector creation, contributed by Daniel
-# Carrera (dcarrera@hush.com) and Carlos Agarie (carlos@onox.com.br).
+# Carrera (dcarrera@hush.com) and Carlos Agarie (carlos.agarie@gmail.com).
+#
+# TODO Make all the shortcuts available through modules, allowing someone
+# to include them to make "MATLAB-like" scripts.
+#
+# There are some questions to be answered before this can be done, tho.
+#++
 
 class NMatrix
 
   class << self
-    # zeros() or zeroes()
     #
-    #     Creates a new matrix of zeros with the dimensions supplied as
-    #     parameters. Optional parameters include:
+    # call-seq:
+    #    zeros(size) -> NMatrix
+    #    zeros(size, dtype) -> NMatrix
+    #    zeros(stype, size, dtype) -> NMatrix
     #
-    #     * A storage type as the first parameter (default is :dense).
-    #     * A dtype as the last parameter (default is :float64).
+    # Creates a new matrix of zeros with the dimensions supplied as
+    # parameters.
+    #
+    # * *Arguments* :
+    #   - +stype+ -> (optional) Default is +:dense+.
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+
+    # * *Returns* :
+    #   - NMatrix filled with zeros.
     #
     # Examples:
     #
-    #   zeros(2) # =>  0.0   0.0   
-    #                  0.0   0.0
+    #   NMatrix.zeros(2) # =>  0.0   0.0
+    #                          0.0   0.0
     #
-    #   zeros([2, 3], :int32) # =>  0  0  0
-    #                            0  0  0
+    #   NMatrix.zeros([2, 3], :int32) # =>  0  0  0
+    #                                       0  0  0
     #
-    #   zeros(:list, [1, 5], :int32) # =>  0  0  0  0  0
+    #   NMatrix.zeros(:list, [1, 5], :int32) # =>  0  0  0  0  0
     #
-    
     def zeros(*params)
       dtype = params.last.is_a?(Symbol) ? params.pop : :float64
       stype = params.first.is_a?(Symbol) ? params.shift : :dense
@@ -54,23 +68,28 @@ class NMatrix
 
       NMatrix.new(stype, dim, 0, dtype)
     end
-
     alias :zeroes :zeros
 
-    # ones()
     #
-    #     Creates a :dense matrix of ones with the dimensions supplied
-    #     as parameters. Optionaly, one can specify a dtype as the last
-    #     parameter (default is :float64).
+    # call-seq:
+    #     ones(size) -> NMatrix
+    #     ones(size, dtype) -> NMatrix
+    #
+    # Creates a matrix filled with ones.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+
+    # * *Returns* :
+    #   - NMatrix filled with ones.
     #
     # Examples:
     #
-    #   ones([1, 3]) # =>  1.0   1.0   1.0
+    #   NMatrix.ones([1, 3]) # =>  1.0   1.0   1.0
     #
-    #   ones([2, 3], :int32) # =>  1  1  1
-    #                              1  1  1
+    #   NMatrix.ones([2, 3], :int32) # =>  1  1  1
+    #                                      1  1  1
     #
-    
     def ones(*params)
       dtype = params.last.is_a?(Symbol) ? params.pop : :float64
       dim = params.first
@@ -78,351 +97,467 @@ class NMatrix
       NMatrix.new(dim, 1, dtype)
     end
 
-    # identity() or eye()
     #
-    #     Creates an identity matrix (square matrix rank 2) of the size
-    #     supplied as a parameter. Optional parameters include:
+    # call-seq:
+    #     eye(size) -> NMatrix
+    #     eye(size, dtype) -> NMatrix
+    #     eye(stype, size, dtype) -> NMatrix
     #
-    #     * A storage type as the first parameter (default is :dense).
-    #     * A dtype as the last parameter (default is :float64).
+    # Creates an identity matrix (square matrix rank 2).
+    #
+    # * *Arguments* :
+    #   - +stype+ -> (optional) Default is +:dense+.
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+
+    # * *Returns* :
+    #   - NMatrix filled with zeros.
     #
     # Examples:
     #
-    #    eye(3) # =>   1.0   0.0   0.0
-    #                  0.0   1.0   0.0
-    #                  0.0   0.0   1.0
+    #    NMatrix.eye(3) # =>   1.0   0.0   0.0
+    #                          0.0   1.0   0.0
+    #                          0.0   0.0   1.0
     #
-    #    eye(3, :int32) # =>   1   0   0
-    #                          0   1   0
-    #                          0   0   1
+    #    NMatrix.eye(3, :int32) # =>   1   0   0
+    #                                  0   1   0
+    #                                  0   0   1
     #
-    #    eye(:yale, 2, :int32) # =>   1   0
-    #                                 0   1
+    #    NMatrix.eye(:yale, 2, :int32) # =>   1   0
+    #                                         0   1
     #
-
     def eye(*params)
       dtype = params.last.is_a?(Symbol) ? params.pop : :float64
       stype = params.first.is_a?(Symbol) ? params.shift : :dense
 
       dim = params.first
-      
+
       # Fill the diagonal with 1's.
       m = NMatrix.zeros(stype, dim, dtype)
-      (0 .. (dim - 1)).each do |i| 
+      (0 .. (dim - 1)).each do |i|
         m[i, i] = 1
       end
-      
+
       m
     end
-
     alias :identity :eye
-    
-    # random()
+
+    #
+    # call-seq:
+    #     random(size) -> NMatrix
     #
-    #     Creates a :dense NMatrix with random numbers between 0 and 1 generated
-    #     by Random::rand. The parameter is the dimension of the matrix.
+    # Creates a +:dense+ NMatrix with random numbers between 0 and 1 generated
+    # by +Random::rand+. The parameter is the dimension of the matrix.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    # * *Returns* :
+    #   - NMatrix filled with zeros.
     #
     # Examples:
     #
-    #   rand([2, 2]) # => 0.4859439730644226   0.1783195585012436
-    #                     0.23193766176700592  0.4503345191478729
+    #   NMatrix.random([2, 2]) # => 0.4859439730644226   0.1783195585012436
+    #                               0.23193766176700592  0.4503345191478729
     #
-
-    def random(*params)
-      dim = params.first
+    def random(size)
       rng = Random.new
 
-      # Must provide the dimension as an Integer for a square matrix or as an
-      # array, e.g. [2, 4, 7].
-      unless dim.is_a?(Integer) || dim.is_a?(Array)
-        raise ArgumentError, "random() accepts only integers or arrays as \
-dimension."
-      end
-
       random_values = []
-      
+
       # Construct the values of the final matrix based on the dimension.
-      if dim.is_a?(Integer)
-        (dim * dim - 1).times { |i| random_values << rng.rand }
+      if size.is_a?(Integer)
+        (size * size - 1).times { |i| random_values << rng.rand }
       else
         # Dimensions given by an array. Get the product of the array elements
         # and generate this number of random values.
-        dim.reduce(1, :*).times { |i| random_values << rng.rand }
+        size.reduce(1, :*).times { |i| random_values << rng.rand }
       end
 
-      NMatrix.new(:dense, dim, random_values, :float64)
+      NMatrix.new(:dense, size, random_values, :float64)
     end
 
-    # seq()
     #
-    #     Creates a :dense NMatrix with a sequence of integers starting at
-    #     zero until the matrix is filled. The parameters to the method
-    #     are the dimensions of the matrix. Optionaly, one can specify a
-    #     dtype as the last parameter (default is :float64).
+    # call-seq:
+    #     seq(size) -> NMatrix
+    #     seq(size, dtype) -> NMatrix
+    #
+    # Creates a matrix filled with a sequence of integers starting at zero.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+
+    # * *Returns* :
+    #   - NMatrix filled with zeros.
     #
     # Examples:
     #
-    #   seq(2) # =>   0   1
+    #   NMatrix.seq(2) # =>   0   1
     #                 2   3
     #
-    #   seq([3, 3], :float32) # =>  0.0  1.0  2.0
-    #                               3.0  4.0  5.0
-    #                               6.0  7.0  8.0
+    #   NMatrix.seq([3, 3], :float32) # =>  0.0  1.0  2.0
+    #                                       3.0  4.0  5.0
+    #                                       6.0  7.0  8.0
     #
-    
     def seq(*params)
       dtype = params.last.is_a?(Symbol) ? params.pop : nil
-      dim = params.first
-      
+      size = params.first
+
       # Must provide the dimension as an Integer for a square matrix or as an
       # 2 element array, e.g. [2,4].
-      unless dim.is_a?(Integer) || (dim.is_a?(Array) && dim.size < 3)
+      unless size.is_a?(Integer) || (size.is_a?(Array) && size.size < 3)
         raise ArgumentError, "seq() accepts only integers or 2-element arrays \
 as dimension."
       end
-      
+
       # Construct the values of the final matrix based on the dimension.
-      if dim.is_a?(Integer)
-        values = (0 .. (dim * dim - 1)).to_a
+      if size.is_a?(Integer)
+        values = (0 .. (size * size - 1)).to_a
       else
         # Dimensions given by a 2 element array.
-        values = (0 .. (dim.first * dim.last - 1)).to_a
+        values = (0 .. (size.first * size.last - 1)).to_a
       end
-      
+
       # It'll produce :int32, except if a dtype is provided.
-      NMatrix.new(:dense, dim, values, dtype)
+      NMatrix.new(:dense, size, values, dtype)
     end
 
-    #########################################
-    # FUNCTIONS FOR MATLAB AND IDL REFUGEES #
-    #########################################
-
     #
-    # These are functions that replicate existing functionality, but
-    # would probably be appreciated by MATLAB or IDL users.
+    # call-seq:
+    #     indgen(size) -> NMatrix
+    #
+    # Returns an integer NMatrix. Equivalent to <tt>seq(n, :int32)</tt>.
     #
+    # * *Arguments* :
+    #   - +size+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NMatrix with dtype +:int32+.
+    #
+    def indgen(size)
+      NMatrix.seq(size, :int32)
+    end
 
-    # indgen() , findgen() , bindgen() , cindgen()
     #
-    #      These IDL functions are similar to seq() but less flexible.
-    #      They produce one-dimensional vectors:
+    # call-seq:
+    #     findgen(size) -> NMatrix
     #
-    #      indgen    -- Integer vector   --   seq(n, :int32)
-    #      findgen   -- Float vector     --   seq(n, :float32)
-    #      bindgen   -- Byte vector      --   seq(n, :byte)
-    #      cindgen   -- Complex vector   --   seq(n, :complex64)
+    # Returns a float NMatrix. Equivalent to <tt>seq(n, :float32)</tt>.
     #
-
-    def indgen(n)
-      NMatrix.seq(n, :int32)
+    # * *Arguments* :
+    #   - +size+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NMatrix with dtype +:float32+.
+    #
+    def findgen(size)
+      NMatrix.seq(size, :float32)
     end
 
-    def findgen(n)
-      NMatrix.seq(n, :float32)
+    #
+    # call-seq:
+    #     bindgen(size) -> NMatrix
+    #
+    # Returns a byte NMatrix. Equivalent to <tt>seq(n, :byte)</tt>.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NMatrix with dtype +:byte+.
+    #
+    def bindgen(size)
+      NMatrix.seq(size, :byte)
     end
 
-    def bindgen(n)
-      NMatrix.seq(n, :byte)
+    #
+    # call-seq:
+    #     cindgen(size) -> NMatrix
+    #
+    # Returns an complex NMatrix. Equivalent to <tt>seq(n, :complex64)</tt>.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NMatrix with dtype +:complex64+.
+    #
+    def cindgen(size)
+      NMatrix.seq(size, :complex64)
     end
 
-    def cindgen(n)
-      NMatrix.seq(n, :complex64)
-    end
-  
   end
 
   #
-  # These shortcuts are to be called directly from a NMatrix object, i.e.:
+  # call-seq:
+  #     column(column_number) -> NMatrix
+  #     column(column_number, get_by) -> NMatrix
   #
-  # >> m = NMatrix.random(3)
-  # >> m.column(2)
-  #
-
-  # column()
+  # Returns the column specified. Uses slicing by copy as default.
   #
-  #     Returns the column specified. The second parameter defaults to
-  #     :copy, which returns a copy of the selected column, but it can be
-  #     specified as :reference, which will return a reference to it.
+  # * *Arguments* :
+  #   - +column_number+ -> Integer.
+  #   - +get_by+ -> Type of slicing to use, +:copy+ or +:reference+.
+  # * *Returns* :
+  #   - A NMatrix representing the requested column as a column vector.
   #
   # Examples:
   #
   #   m = NMatrix.new(2, [1, 4, 9, 14], :int32) # =>  1   4
   #                                                   9  14
-  #   
+  #
   #   m.column(1) # =>   4
   #                     14
   #
-    
   def column(column_number, get_by = :copy)
     unless [:copy, :reference].include?(get_by)
       raise ArgumentError, "column() 2nd parameter must be :copy or :reference"
     end
-    
+
     if get_by == :copy
       self.slice(0 ... self.shape[0], column_number)
     else # by reference
       self[0 ... self.shape[0], column_number]
     end
   end
+
+  alias :col :column
+
+  #
+  # call-seq:
+  #     row(row_number) -> NMatrix
+  #     row(row_number, get_by) -> NMatrix
+  #
+  # * *Arguments* :
+  #   - +row_number+ -> Integer.
+  #   - +get_by+ -> Type of slicing to use, +:copy+ or +:reference+.
+  # * *Returns* :
+  #   - A NMatrix representing the requested row .
+  #
+  def row(row_number, get_by = :copy)
+    unless [:copy, :reference].include?(get_by)
+      raise ArgumentError, "row() 2nd parameter must be :copy or :reference"
+    end
+
+    if get_by == :copy
+      self.slice(row_number, 0 ... self.shape[1])
+    else # by reference
+      self[row_number, 0 ... self.shape[1]]
+    end
+  end
 end
 
 class NVector < NMatrix
-  
+
   class << self
-    # zeros() or zeroes()
     #
-    #     Creates a new matrix of zeros with the dimensions supplied as
-    #     parameters. Optional parameters include:
+    # call-seq:
+    #     zeros(size) -> NMatrix
+    #     zeros(size, dtype) -> NMatrix
+    #
+    # Creates a new matrix of zeros with the dimensions supplied as
+    # parameters.
     #
-    #     * A storage type as the first parameter (default is :dense).
-    #     * A dtype as the last parameter (default is :float64).
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+.
+    # * *Returns* :
+    #   - NVector filled with zeros.
     #
     # Examples:
     #
-    #   zeros(2) # =>  0.0   0.0   
+    #   NVector.zeros(2) # =>  0.0
+    #                          0.0
     #
-    #   zeros(3, :int32) # =>  0  0  0
+    #   NVector.zeros(3, :int32) # =>  0
+    #                                  0
+    #                                  0
     #
-    
-    def zeros(*params)
-      dtype = params.last.is_a?(Symbol) ? params.pop : :float64
-      dim = params.first
-
-      NVector.new(dim, 0, dtype)
+    def zeros(size, dtype = :float64)
+      NVector.new(size, 0, dtype)
     end
-
     alias :zeroes :zeros
 
-    # ones()
     #
-    #     Creates a :dense matrix of ones with the dimensions supplied
-    #     as parameters. Optionaly, one can specify a dtype as the last
-    #     parameter (default is :float64).
+    # call-seq:
+    #     ones(size) -> NVector
+    #     ones(size, dtype) -> NVector
+    #
+    # Creates a vector of ones with the dimensions supplied as
+    # parameters.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+.
+    # * *Returns* :
+    #   - NVector filled with ones.
     #
     # Examples:
     #
-    #   ones(3) # =>  1.0   1.0   1.0
+    #   NVector.ones(2) # =>  1.0
+    #                         1.0
     #
-    #   ones(2, :int32) # =>  1  1
+    #   NVector.ones(3, :int32) # =>  1
+    #                                 1
+    #                                 1
     #
-    
-    def ones(*params)
-      dtype = params.last.is_a?(Symbol) ? params.pop : :float64
-      dim = params.first
-
-      NVector.new(dim, 1, dtype)
+    def ones(size, dtype = :float64)
+      NVector.new(size, 1, dtype)
     end
-    
-    # random()
+
+    #
+    # call-seq:
+    #     random(size) -> NVector
     #
-    #     Creates a :dense NMatrix with random numbers between 0 and 1 generated
-    #     by Random::rand. The parameter is the dimension of the matrix.
+    # Creates a vector with random numbers between 0 and 1 generated by
+    # +Random::rand+ with the dimensions supplied as parameters.
+    #
+    # * *Arguments* :
+    #   - +size+ -> Array (or integer for square matrix) specifying the dimensions.
+    #   - +dtype+ -> (optional) Default is +:float64+.
+    # * *Returns* :
+    #   - NVector filled with random numbers generated by the +Random+ class.
     #
     # Examples:
     #
-    #   rand(2) # => 0.4859439730644226   0.1783195585012436
+    #   NVector.rand(2) # =>  0.4859439730644226
+    #                         0.1783195585012436
     #
-
-    def random(*params)
+    def random(size)
       rng = Random.new
-      dim = params.first
 
       random_values = []
-      dim.times { |i| random_values << rng.rand }
-      
-      NVector.new(dim, random_values, :float64)
+      size.times { |i| random_values << rng.rand }
+
+      NVector.new(size, random_values, :float64)
     end
 
-    # seq()
     #
-    #     Creates a :dense NMatrix with a sequence of integers starting at
-    #     zero until the matrix is filled. The parameters to the method
-    #     are the dimensions of the matrix. Optionaly, one can specify a
-    #     dtype as the last parameter (default is :float64).
+    # call-seq:
+    #     seq(n) -> NVector
+    #     seq(n, dtype) -> NVector
+    #
+    # Creates a vector with a sequence of +n+ integers starting at zero. You
+    # can choose other types based on the dtype parameter.
+    #
+    # * *Arguments* :
+    #   - +n+ -> Number of integers in the sequence.
+    #   - +dtype+ -> (optional) Default is +:int64+.
+    # * *Returns* :
+    #   - NVector filled with +n+ integers.
     #
     # Examples:
     #
-    #   seq(2) # =>   0   1
+    #   NVector.seq(2) # =>  0
+    #                        1
     #
-    #   seq(3, :float32) # =>  0.0  1.0  2.0
+    #   NVector.seq(3, :float32) # =>  0.0
+    #                                  1.0
+    #                                  2.0
     #
-    
-    def seq(*params)
-      dtype = params.last.is_a?(Symbol) ? params.pop : nil
-      dim = params.first
-      
-      unless dim.is_a?(Integer)
-        raise ArgumentError, "NVector::seq() only accepts integers as \
-dimension."
+    def seq(n, dtype = :int64)
+      unless n.is_a?(Integer)
+        raise ArgumentError, "NVector::seq() only accepts integers as size."
       end
-            
-      values = (0 .. (dim - 1)).to_a
-      
-      NVector.new(dim, values, dtype)
-    end
 
-    #########################################
-    # FUNCTIONS FOR MATLAB AND IDL REFUGEES #
-    #########################################
+      values = (0 ... n).to_a
 
-    #
-    # These are functions that replicate existing functionality, but
-    # would probably be appreciated by MATLAB or IDL users.
-    #
+      NVector.new(n, values, dtype)
+    end
 
-    # indgen() , findgen() , bindgen() , cindgen()
     #
-    #      These IDL functions are similar to seq() but less flexible.
-    #      They produce one-dimensional vectors:
+    # call-seq:
+    #     indgen(n) -> NVector
     #
-    #      indgen    -- Integer vector   --   seq(n, :int32)
-    #      findgen   -- Float vector     --   seq(n, :float32)
-    #      bindgen   -- Byte vector      --   seq(n, :byte)
-    #      cindgen   -- Complex vector   --   seq(n, :complex64)
+    # Returns an integer NVector. Equivalent to <tt>seq(n, :int32)</tt>.
+    #
+    # * *Arguments* :
+    #   - +n+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NVector filled with +n+ integers of dtype +:int32+.
     #
-
     def indgen(n)
       NVector.seq(n, :int32)
     end
 
+    #
+    # call-seq:
+    #     findgen(n) -> NVector
+    #
+    # Returns a float NVector. Equivalent to <tt>seq(n, :float32)</tt>.
+    #
+    # * *Arguments* :
+    #   - +n+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NVector filled with +n+ integers of dtype +:float32+.
+    #
     def findgen(n)
       NVector.seq(n, :float32)
     end
 
+    #
+    # call-seq:
+    #     bindgen(n) -> NVector
+    #
+    # Returns a byte NVector. Equivalent to <tt>seq(n, :byte)</tt>.
+    #
+    # * *Arguments* :
+    #   - +n+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NVector filled with +n+ integers of dtype +:byte+.
+    #
     def bindgen(n)
       NVector.seq(n, :byte)
     end
 
+    #
+    # call-seq:
+    #     cindgen(n) -> NVector
+    #
+    # Returns a complex NVector. Equivalent to <tt>seq(n, :complex64)</tt>.
+    #
+    # * *Arguments* :
+    #   - +n+ -> Size of the sequence.
+    # * *Returns* :
+    #   - NVector filled with +n+ integers of dtype +:complex64+.
+    #
     def cindgen(n)
       NVector.seq(n, :complex64)
     end
-   
-    # linspace()
+
     #
-    #      This MATLAB function somewhat resembles seq(), but it differs
-    #      enough that is likely to be legitimately useful to non-MATLAB
-    #      refugees. This function takes three parameter, the last one
-    #      being an integer.
+    # call-seq:
+    #     linspace(a, b) -> NVector
+    #     linspace(a, b, n) -> NVector
     #
-    #      linspace( a, b, n )
+    # Returns a NVector with +n+ values of dtype +:float64+ equally spaced from
+    # +a+ to +b+, inclusive.
     #
-    #      This returns a vector with n values equally spaced from a to b,
-    #      inclusive.
-    #      
-    #      Following the MATLAB implementation, if n isn't provided it's
-    #      assumed to be 100.
+    # Following the MATLAB implementation, if n isn't provided it's assumed to
+    # be 100.
     #
-    # Ex:  x = linspace(0, pi, 1000)
-    #      y = sin(x)
+    # * *Arguments* :
+    #   - +a+ -> The first value in the sequence.
+    #   - +b+ -> The last value in the sequence.
+    #   - +n+ -> The number of elements.
+    # * *Returns* :
+    #   - n-by-1 NMatrix with +n+ +:float64+ values.
+    #
+    # Example:
+    #   x = NVector.linspace(0, Math::PI, 1000)
+    #   => #<NMatrix:0x007f83921992f0shape:[1000,1] dtype:float64 stype:dense>
+    #
+    #   x.pp
+    #     [0.0]
+    #     [0.0031447373909807737]
+    #     [0.006289474781961547]
+    #     ...
+    #     [3.135303178807831]
+    #     [3.138447916198812]
+    #     [3.141592653589793]
+    #   => nil
     #
-
     def linspace(a, b, n = 100)
       # See: http://www.mathworks.com/help/matlab/ref/linspace.html
       # Formula:  seq(n) * step + a
-      
+
       # step = ((b - a) / (n - 1))
       step = (b - a) * (1.0 / (n - 1))
-      
+
       # dtype = :float64 is used to prevent integer coercion.
       result = NVector.seq(n, :float64) * NVector.new(n, step, :float64)
       result += NVector.new(n, a, :float64)
@@ -431,36 +566,39 @@ dimension."
   end
 end
 
-# NMatrix needs to have a succinct way to create a matrix by specifying
-# the components directly. This is very usefeul for using NMatrix as an
-# advanced calculator, it is useful for learning NMatrix and it is also
-# useful for testing language features or developing algorithms.
+# NMatrix needs to have a succinct way to create a matrix by specifying the
+# components directly. This is very useful for using it as an advanced
+# calculator, it is useful for learning how to use, for testing language
+# features and for developing algorithms.
 #
-# The N[] function provides a way to create a matrix in a way that is
-# very short and very natural, simply by specifying the components in
-# the traditional Ruby array syntax.  Optionally, one can specify a
-# dtype as the last parameter (default is :float64).
+# The N class provides a way to create a matrix in a way that is compact and
+# natural. The components are specified using Ruby array syntax. Optionally,
+# one can specify a dtype as the last parameter (default is :float64).
 #
-# a = N[ 1,2,3,4 ]          =>  1.0  2.0  3.0  4.0
+# Examples:
 #
-# a = N[ 1,2,3,4, :int32 ]  =>  1  2  3  4
+#   a = N[ 1,2,3,4 ]          =>  1.0  2.0  3.0  4.0
 #
-# a = N[ [1,2,3], [3,4,5] ] =>  1.0  2.0  3.0
-#                               3.0  4.0  5.0
+#   a = N[ 1,2,3,4, :int32 ]  =>  1  2  3  4
 #
+#   a = N[ [1,2,3], [3,4,5] ] =>  1.0  2.0  3.0
+#                                 3.0  4.0  5.0
 #
 # SYNTAX COMPARISON:
 #
-#     MATLAB:		a = [ [1 2 3] ; [4 5 6] ]   or  [ 1 2 3 ; 4 5 6 ]
-#     IDL:			a = [ [1,2,3] , [4,5,6] ]
-#     NumPy:		a = array( [1,2,3], [4,5,6] )
+#   MATLAB:		a = [ [1 2 3] ; [4 5 6] ]   or  [ 1 2 3 ; 4 5 6 ]
+#   IDL:			a = [ [1,2,3] , [4,5,6] ]
+#   NumPy:		a = array( [1,2,3], [4,5,6] )
 #
-#     SciRuby:      a = N[ [1,2,3], [4,5,6] ]
-#     Ruby array:   a =  [ [1,2,3], [4,5,6] ]
+#   SciRuby:      a = N[ [1,2,3], [4,5,6] ]
+#   Ruby array:   a =  [ [1,2,3], [4,5,6] ]
 #
-
 class N
   class << self
+    #
+    # call-seq:
+    #     N[array-of-arrays, dtype = nil]
+    #
     def [](*params)
       dtype = params.last.is_a?(Symbol) ? params.pop : nil
 
@@ -470,7 +608,7 @@ class N
       foo = params
       while foo.is_a?(Array)
         dim[i] = foo.length
-        foo    = foo[0]
+        foo = foo[0]
         i += 1
       end
 
@@ -479,8 +617,3 @@ class N
     end
   end
 end
-
-# TODO Make all the shortcuts available through modules, allowing someone
-# to include them to make "MATLAB-like" scripts.
-#
-# There are some questions to be answered before this can be done, tho.