nest.rb in rubyvis-0.1.6

- old
+ new

@@ -1,54 +1,53 @@
 module Rubyvis
   ##
-  # Returns a {@link pv.Nest} operator for the specified array. This is a
-  # convenience factory method, equivalent to <tt>new pv.Nest(array)</tt>.
+  # Returns a Nest operator for the specified array. This is a
+  # convenience factory method, equivalent to <tt>Nest.new(array)</tt>.
   #
-  # @see pv.Nest
+  # @see Rubyvis::Nest
   # @param {array} array an array of elements to nest.
   # @returns {Nest} a nest operator for the specified array.
   ##
   def self.nest(array)
     Nest.new(array)
   end
+  # :stopdoc:
   class NestedArray
     attr_accessor :key, :values
     def initialize(opts)
       @key=opts[:key]
       @values=opts[:values]
     end
     def ==(var)
       key==var.key and values=var.values
     end
   end
-  ##
-  # Constructs a nest operator for the specified array. This constructor should
-  # not be invoked directly; use {@link pv.nest} instead.
-  #
-  # @class Represents a {@link Nest} operator for the specified array. Nesting
+  # :startdoc: 
+  
+  # Represents a Nest operator for the specified array. Nesting
   # allows elements in an array to be grouped into a hierarchical tree
   # structure. The levels in the tree are specified by <i>key</i> functions. The
   # leaf nodes of the tree can be sorted by value, while the internal nodes can
   # be sorted by key. Finally, the tree can be returned either has a
-  # multidimensional array via {@link #entries}, or as a hierarchical map via
-  # {@link #map}. The {@link #rollup} routine similarly returns a map, collapsing
+  # multidimensional array via Nest.entries, or as a hierarchical map via
+  # Nest.map. The Nest.rollup routine similarly returns a map, collapsing
   # the elements in each leaf node using a summary function.
   #
-  # <p>For example, consider the following tabular data structure of Barley
+  # For example, consider the following tabular data structure of Barley
   # yields, from various sites in Minnesota during 1931-2:
   #
   #   { yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
   #   { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
   #   { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }
   #
   # To facilitate visualization, it may be useful to nest the elements first by
   # year, and then by variety, as follows:
   #
-  # <pre>var nest = pv.nest(yields)
-  #     .key(function(d) d.year)
-  #     .key(function(d) d.variety)
-  #     .entries();</pre>
+  #     var nest = Rubyvis.nest(yields)
+  #     .key(lambda {|d|  d.year})
+  #     .key(lambda {|d| d.variety})
+  #     .entries();
   #
   # This returns a nested array. Each element of the outer array is a key-values
   # pair, listing the values for each distinct key:
   #
   # <pre>{ key: 1931, values: [
@@ -66,29 +65,30 @@
   #   ] },
   # { key: 1932, values: ... }</pre>
   #
   # Further details, including sorting and rollup, is provided below on the
   # corresponding methods.
-  #
-  # @param {array} array an array of elements to nest.
-  #/
   class Nest
     attr_accessor :array, :keys, :order
+    ##
+    # Constructs a nest operator for the specified array. This constructor should
+    # not be invoked directly; use Rubyvis.nest instead.
+    
     def initialize(array)
       @array=array
       @keys=[]
       @order=nil
     end
     def key(k)
       @keys.push(k)
       return self
     end
     def sort_keys(order=nil)
-      keys[keys.size-1].order = order.nil? ? pv.natural_order : order
+      keys[keys.size-1].order = order.nil? ? Rubyvis.natural_order : order
       return self
     end
     def sort_values(order=nil)
-      @order = order.nil? ? pv.natural_order : order
+      @order = order.nil? ? Rubyvis.natural_order : order
       return self
     end
     def map
       #i=0
       map={} 