* lib/test/unit.rb: rearranged documentation for RDoc's sake.

* lib/matrix.rb: improved documentation.
 * lib/net/http.rb: slight documentation formatting improvement.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5597 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,9 @@
+Sun Feb  1 16:15:00 2004  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* lib/test/unit.rb: rearranged documentation for RDoc's sake.
+	* lib/matrix.rb: improved documentation.
+	* lib/net/http.rb: slight documentation formatting improvement.
+
 Sun Feb  1 05:30:06 2004  Tanaka Akira  <akr@m17n.org>
 
 	* lib/open-uri.rb (URI::Generic#find_proxy): warn HTTP_PROXY.

lib/matrix.rb

@@ -1,5 +1,5 @@
 #!/usr/local/bin/ruby
-#
+#--
 #   matrix.rb - 
 #       $Release Version: 1.0$
 #       $Revision: 1.11 $
@@ -7,164 +7,22 @@
 #       Original Version from Smalltalk-80 version
 #          on July 23, 1985 at 8:37:17 am
 #       by Keiju ISHITSUKA
+#++
 #
-# --
+# = matrix.rb
 #
-#   Matrix[[1,2,3],
+# An implementation of Matrix and Vector classes.
-#	      :
-#	   [3,4,5]]
-#   Matrix[row0,
-#          row1,
-#	    :
-#          rown]
 #
+# Author:: Keiju ISHITSUKA
+# Documentation:: Gavin Sinclair (sourced from <i>Ruby in a Nutshell</i> (Matsumoto, O'Reilly)) 
 #
-# module ExceptionForMatrix::
+# See classes Matrix and Vector for documentation. 
-#   Exceptions:
-#	ErrDimensionMismatch
-#	    number of column/row do not match
-#	ErrNotRegular
-#	    not a regular matrix
-#	ErrOperationNotDefined
-#	    specified operator is not defined (yet)
 #
-# class Matrix
+
-#   include ExceptionForMatrix
-#
-#   Methods:
-#   class methods:
-#	Matrix.[](*rows)
-#	    creates a matrix where `rows' indicates rows. 
-#	    `rows' is an array of arrays, 
-#	    e.g, Matrix[[11, 12], [21, 22]]
-#	Matrix.rows(rows, copy = true)
-#	    creates a matrix where `rows' indicates rows. 
-#           if optional argument `copy' is false, use the array as
-#	    internal structure of the metrix without copying.
-#	Matrix.columns(columns)
-#           creates a new matrix using `columns` as set of colums vectors.
-#	Matrix.diagonal(*values)
-#	    creates a matrix where `columns' indicates columns. 
-#	Matrix.scalar(n, value)
-#	    creates a diagonal matrix such that the diagal compornents is
-#	    given by `values'.
-#	Matrix.scalar(n, value)
-#	    creates an n-by-n scalar matrix such that the diagal compornent is 
-#	    given by `value'.
-#	Matrix.identity(n)
-#	Matrix.unit(n)
-#	Matrix.I(n)
-#	    creates an n-by-n unit matrix.
-#	Matrix.zero(n)
-#	    creates an n-by-n zero matrix.
-#	Matrix.row_vector(row)
-#	    creates a 1-by-n matrix such the row vector is `row'. 
-#	    `row' is specifed as a Vector or an Array.
-#	Matrix.column_vector(column)
-#	    creates a 1-by-n matrix such that column vector is `column'. 
-#	    `column' is specifed as a Vector or an Array.
-#   accessing:
-#	[](i, j)
-#	    returns (i,j) compornent
-#	row_size
-#	    returns the number of rows
-#	column_size
-#	    returns the number of columns
-#	row(i)
-#	    returns the i-th row vector. 
-#	    when the block is supplied for the method, the block is iterated
-#	    over all row vectors. 
-#	column(j)
-#	    returns the jth column vector. 
-#	    when the block is supplied for the method, the block is iterated
-#	    over all column vectors. 
-#	collect
-#	map
-#	    creates a matrix which is the result of iteration of given
-#	    block over all compornents. 
-#	minor(*param)
-#	    returns sub matrix. parameter is specified as the following:
-#	    1. from_row, row_size, from_col, size_col
-#	    2. from_row..to_row, from_col..to_col
-#   TESTING:
-#	regular?
-#	    Is regular?
-#	singular?
-#	    Is singular? i.e. Is non-regular?
-#	square?
-#	    Is square?
-#   ARITHMETIC:
-#	*(m)
-#	    times
-#	+(m)
-#	    plus
-#	-(m)
-#	    minus
-#	/(m)
-#	    self * m.inv
-#	inverse
-#	inv
-#	    inverse
-#	**
-#	    power
-#   Matrix functions:
-#	determinant
-#	det
-#	    returns the determinant
-#	rank
-#	    returns the rank
-#	trace
-#	tr
-#	    returns the trace
-#	transpose
-#	t
-#	    returns the transposed
-#   CONVERTING:
-#	coerce(other)
-#	row_vectors
-#	    array of row vectors
-#	column_vectors
-#	    array of column vectors
-#	to_a
-#	    converts to Array of Arrays
-#   PRINTING:
-#	to_s
-#	    returns string representation
-#	inspect
-#
-# class Vector
-#   include ExceptionForMatrix
-#
-#   INSTANCE CREATION:
-#	Vector.[](*array)
-#	Vector.elements(array, copy = true)
-#   ACCSESSING:
-#	[](i)
-#	size
-#   ENUMRATIONS:
-#	each2(v)
-#	collect2(v)
-#   ARITHMETIC:
-#	*(x) "is matrix or number"
-#	+(v)
-#	-(v)
-#   VECTOR FUNCTIONS:
-#	inner_product(v)
-#	collect
-#	map
-#	map2(v)
-#	r
-#   CONVERTING:
-#	covector
-#	to_a
-#	coerce(other)
-#   PRINTING:
-#	to_s
-#	inspect
 
 require "e2mmap.rb"
 
-module ExceptionForMatrix
+module ExceptionForMatrix # :nodoc:
   extend Exception2MessageMapper
   def_e2message(TypeError, "wrong argument type %s (expected %s)")
   def_e2message(ArgumentError, "Wrong # of arguments(%d for %d)")
@@ -175,18 +33,77 @@ module ExceptionForMatrix
 end
 
 #
-# Represents a mathematical matrix, and provides methods for creating
+# The +Matrix+ class represents a mathematical matrix, and provides methods for creating
-# special-case matrices (zero, identity, diagonal, singular, vector), operating
+# special-case matrices (zero, identity, diagonal, singular, vector), operating on them
-# on them arithmetically and algebraically, and determining their mathematical
+# arithmetically and algebraically, and determining their mathematical properties (trace, rank,
-# properties (trace, rank, inverse, determinant).
+# inverse, determinant).
-#
-# The capabilities of the class indicated in the above paragraph are probably
-# not exhaustive.  Browse the methods and their documentation for more
-# information.
 #
 # Note that although matrices should theoretically be rectangular, this is not
 # enforced by the class.
 #
+# Also note that the determinant of integer matrices may be incorrectly calculated unless you
+# also <tt>require 'mathn'</tt>.  This may be fixed in the future.
+#
+# == Method Catalogue
+#
+# To create a matrix:
+# * <tt> Matrix[*rows]                  </tt>
+# * <tt> Matrix.[](*rows)               </tt>
+# * <tt> Matrix.rows(rows, copy = true) </tt>
+# * <tt> Matrix.columns(columns)        </tt>
+# * <tt> Matrix.diagonal(*values)       </tt>
+# * <tt> Matrix.scalar(n, value)        </tt>
+# * <tt> Matrix.scalar(n, value)        </tt>
+# * <tt> Matrix.identity(n)             </tt>
+# * <tt> Matrix.unit(n)                 </tt>
+# * <tt> Matrix.I(n)                    </tt>
+# * <tt> Matrix.zero(n)                 </tt>
+# * <tt> Matrix.row_vector(row)         </tt>
+# * <tt> Matrix.column_vector(column)   </tt>
+#
+# To access Matrix elements/columns/rows/submatrices/properties: 
+# * <tt>  [](i, j)                      </tt>
+# * <tt> #row_size                      </tt>
+# * <tt> #column_size                   </tt>
+# * <tt> #row(i)                        </tt>
+# * <tt> #column(j)                     </tt>
+# * <tt> #collect                       </tt>
+# * <tt> #map                           </tt>
+# * <tt> #minor(*param)                 </tt>
+#
+# Properties of a matrix:
+# * <tt> #regular?                      </tt>
+# * <tt> #singular?                     </tt>
+# * <tt> #square?                       </tt>
+#
+# Matrix arithmetic:
+# * <tt>  *(m)                          </tt>
+# * <tt>  +(m)                          </tt>
+# * <tt>  -(m)                          </tt>
+# * <tt> #/(m)                          </tt>
+# * <tt> #inverse                       </tt>
+# * <tt> #inv                           </tt>
+# * <tt>  **                            </tt>
+#
+# Matrix functions:
+# * <tt> #determinant                   </tt>
+# * <tt> #det                           </tt>
+# * <tt> #rank                          </tt>
+# * <tt> #trace                         </tt>
+# * <tt> #tr                            </tt>
+# * <tt> #transpose                     </tt>
+# * <tt> #t                             </tt>
+#
+# Conversion to other data types:
+# * <tt> #coerce(other)                 </tt>
+# * <tt> #row_vectors                   </tt>
+# * <tt> #column_vectors                </tt>
+# * <tt> #to_a                          </tt>
+#
+# String representations:
+# * <tt> #to_s                          </tt>
+# * <tt> #inspect                       </tt>
+#
 class Matrix
   @RCS_ID='-$Id: matrix.rb,v 1.11 1999/10/06 11:01:53 keiju Exp keiju $-'
   
@@ -1028,11 +945,46 @@ class Matrix
   end
 end
 
-#----------------------------------------------------------------------
+
 #
-#    - 
+# The +Vector+ class represents a mathematical vector, which is useful in its own right, and
+# also consitutes a row or column of a Matrix.
+#
+# == Method Catalogue
+#
+# To create a Vector:
+# * <tt>  Vector.[](*array)                   </tt>
+# * <tt>  Vector.elements(array, copy = true) </tt>
+#
+# To access elements:
+# * <tt>  [](i)                               </tt>
+#
+# To enumerate the elements:
+# * <tt> #each2(v)                            </tt>
+# * <tt> #collect2(v)                         </tt>
+#
+# Vector arithmetic:
+# * <tt>  *(x) "is matrix or number"          </tt>
+# * <tt>  +(v)                                </tt>
+# * <tt>  -(v)                                </tt>
+#
+# Vector functions:
+# * <tt> #inner_product(v)                    </tt>
+# * <tt> #collect                             </tt>
+# * <tt> #map                                 </tt>
+# * <tt> #map2(v)                             </tt>
+# * <tt> #r                                   </tt>
+# * <tt> #size                                </tt>
+#
+# Conversion to other data types:
+# * <tt> #covector                            </tt>
+# * <tt> #to_a                                </tt>
+# * <tt> #coerce(other)                       </tt>
+#
+# String representations:
+# * <tt> #to_s                                </tt>
+# * <tt> #inspect                             </tt>
 #
-#----------------------------------------------------------------------
 class Vector
   include ExceptionForMatrix
   
@@ -1318,5 +1270,3 @@ end
 
 # Documentation comments:
 #  - Matrix#coerce and Vector#coerce need to be documented
-#  - Matrix class methods (aliases) unit and I don't appear in RDoc output
-#    becuase of "class << Matrix".  This is an RDoc issue.

lib/net/http.rb

@@ -14,7 +14,7 @@
 # modify this program under the same terms of ruby itself ---
 # Ruby Distribution License or GNU General Public License.
 #
-# See Net:::HTTP for an overview and examples. 
+# See Net::HTTP for an overview and examples. 
 # 
 # NOTE: You can find Japanese version of this document here:
 # http://www.ruby-lang.org/ja/man/?cmd=view;name=net%2Fhttp.rb
@@ -39,7 +39,7 @@ module Net # :nodoc:
   # This library provides your program functions to access WWW
   # documents via HTTP, Hyper Text Transfer Protocol version 1.1.
   # For details of HTTP, refer [RFC2616]
-  # ((<URL:http://www.ietf.org/rfc/rfc2616.txt>)).
+  # (http://www.ietf.org/rfc/rfc2616.txt).
   # 
   # == Examples
   # 
@@ -1787,10 +1787,10 @@ module Net # :nodoc:
   end
 
 
-  # :enddoc:
+  # :stopdoc:
 
-  #--
   # for backward compatibility
+ 
   class HTTP
     ProxyMod = ProxyDelta
   end

lib/test/unit.rb

@@ -1,6 +1,4 @@
-require 'test/unit/testcase'
+#
-require 'test/unit/autorunner'
-
 # = Test::Unit - Ruby Unit Testing Framework
 # 
 # == Introduction
@@ -256,10 +254,13 @@ require 'test/unit/autorunner'
 # I'd really like to get feedback from all levels of Ruby
 # practitioners about typos, grammatical errors, unclear statements,
 # missing points, etc., in this document (or any other).
+#
 
+require 'test/unit/testcase'
+require 'test/unit/autorunner'
 
-module Test
+module Test # :nodoc:
-  # For documentation, see module Test
+  # For documentation, see file test/unit.rb.
   module Unit
     def self.run=(flag)
       @run = flag