- added some api documentation to Ruport::Data::Table and Array

git-svn-id: http://stonecode.svnrepository.com/svn/ruport/trunk/ruport@131 bb2e8eb0-7117-0410-aac4-c024b40ed5f7

lib/ruport/data/table.rb

@@ -5,14 +5,38 @@
 # Copyright 2006 by respective content owners, all rights reserved.
 
 class Array
+  # Converts an array to a Ruport::Data::Table object, ready to
+  # generate reports with.
+  #
+  #   [[1,2],[3,4]].to_table(%w[a b])
   def to_table(options={})
     options = { :column_names => options } if options.kind_of? Array 
     Ruport::Data::Table.new({:data => self}.merge(options))
   end
 end
 
 module Ruport::Data
+
+  # This class is one of the core class for building and working with data in
+  # Ruport. The idea is to get your data into a standard form, regardless of 
+  # it's source (files, a database, manual arrays, active record, CSV).
+  # 
+  # Table is intended to be used as the data store for structured, tabular
+  # data - Ruport::Data::Set is an alternate intermediary data store intended
+  # for less structured data.
+  #
+  # Once your data is into a Ruport::Data::Table object, it can be manipulated
+  # to suit your needs, then used to build a report.
+  #
+  # Included in this class are methods to create Table's manually and from CSV.
+  # For building a table using ActiveRecord, have a look at Ruport::Reportable 
   class Table < Collection
+
+    # Creates a new table based on the supplied options
+    # Valid options are :data and :column_names
+    #
+    #   table = Table.new({:data => [1,2,3], [3,4,5], 
+    #                      :column_names => %w[a b c]})
     def initialize(options={})
       @column_names = options[:column_names].dup if options[:column_names]
       @data         = []
@@ -21,20 +45,42 @@ def initialize(options={})
 
     attr_reader :column_names
 
+    # Sets the column names for this table.
+    # Single parameter should be an array listing the names
+    #
+    #   tbl = Table.new({:data => [1,2,3], [3,4,5], :column_names => %w[a b c]})
+    #   tbl.column_names = %w[e f g]
     def column_names=(other)
       @column_names = other.dup
       map { |r| r.attributes = @column_names }
     end
 
+    # Compares this table to another table and returns true if
+    # both the data and column names are equal
+    #
+    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   two = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   one.eql?(two) #=> true
     def eql?(other)
       data.eql?(other.data) && column_names.eql?(other.column_names) 
     end
     alias_method :==, :eql?
 
+    # Uses ruports inbuilt text plugin to render this table into a string
+    # 
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   puts data.to_s
     def to_s
       as(:text)
     end
 
+    # Used too add extra data to the table. The single parameter can be an 
+    # Array, Hash or Ruport::Data::Record.
+    #
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   data << [8,9]
+    #   data << { :a => 4, :b => 5}
+    #   data << Ruport::Data::Record.new [5,6], :attributes => %w[a b]
     def <<(other)
       case other
       when Array
@@ -50,7 +96,12 @@ def <<(other)
       end
       self
     end
-
+
+    # Reorders the columns that exist in the table. Operates directly 
+    # on this table.
+    #
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   data.reorder!([1,0])  
     def reorder!(*indices)
       indices = indices[0] if indices[0].kind_of? Array
       @column_names = if indices.all? { |i| i.kind_of? Integer }
@@ -61,10 +112,21 @@ def reorder!(*indices)
       @data.each { |r| r.reorder! *indices }; self
     end
 
+    # returns a copy of the table with it's columns in the requested order
+    #
+    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   two = one.reorder!([1,0])  
     def reorder(*indices)
       dup.reorder! *indices
     end
 
+    # adds an extra column to the table. Accepts an options Hash as its
+    # only parameter which should contain 2 keys - :name and :fill
+    # :name species the new columns name, and :fill the default value to 
+    # use for the column in existing rows.
+    #   
+    #   data = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   data.append_coulmn({:name => 'new_column', :fill => 1)
     def append_column(options={})
       self.column_names += [options[:name]]  if options[:name]
       if block_given?
@@ -74,12 +136,20 @@ def append_column(options={})
       end
     end
 
+    # Create a shallow copy of the table: the same data elements are referenced
+    # by both the old and new table
+    #
+    #   one = Table.new({:data => [1,2], [3,4], :column_names => %w[a b]})
+    #   two = one.dup
     def dup
       a = self.class.new(:data => @data, :column_names => @column_names)
       a.tags = tags.dup
       return a
     end
 
+    # loads a CSV file directly into a table using the fasterCSV library.
+    #   
+    #   data = Table.load('mydata.csv')
     def self.load(csv_file, options = {})
       options = {:has_names => true}.merge(options)
       require "fastercsv"
@@ -98,6 +168,7 @@ def self.load(csv_file, options = {})
       end ; loaded_data
     end
 
+    # Used for advanced grouping functionality. More info to come
     def split(options={})
       if options[:group].kind_of? Array
         group = map { |r| options[:group].map { |e| r[e] } }.uniq