--- trunk/jsFind.pm	2004/07/26 20:30:12	11
+++ trunk/jsFind.pm	2004/08/28 14:31:58	12
@@ -7,6 +7,15 @@
 
 our $VERSION = '0.03';
 
+use Exporter 'import';
+use Carp;
+
+our @ISA = qw(Exporter);
+
+BEGIN {
+	import 'jsFind::Node';
+}
+
 =head1 NAME
 
 jsFind - generate index for jsFind using B-Tree
@@ -14,8 +23,19 @@
 =head1 SYNOPSIS
 
   use jsFind;
-
-
+  my $t = new jsFind(B => 4);
+  my $f = 1;
+  foreach my $k (qw{minima ut dolorem sapiente voluptatem}) {
+  	$t->B_search(Key => $k,
+  		Data => {
+  			"path" => {
+  			t => "word $k",
+  			f => $f },
+  		},
+  		Insert => 1,
+  		Append => 1,
+  	);
+  }
 
 =head1 DESCRIPTION
 
@@ -37,24 +57,12 @@
 
 =back
 
-=head1 METHODS
-
-This module contains two packages C<jsFind> and C<jsFind::Node>.
+=head1 jsFind methods
 
-=head2 jsFind methods
+C<jsFind> is mode implementing methods which you, the user, are going to
+use to create indexes.
 
-=cut
-
-use Exporter 'import';
-use Carp;
-
-our @ISA = qw(Exporter);
-
-BEGIN {
-	import 'jsFind::Node';
-}
-
-=head3 new
+=head2 new
 
 Create new tree. Arguments are C<B> which is maximum numbers of keys in
 each node and optional C<Root> node. Each root node may have child nodes.
@@ -83,7 +91,7 @@
   bless { B => $B, Root => $Root } => $package;
 }
 
-=head3 B_search
+=head2 B_search
 
 Search, insert, append or replace data in B-Tree
 
@@ -225,7 +233,7 @@
   }
 }
 
-=head3 B
+=head2 B
 
 Return B (maximum number of keys)
 
@@ -237,7 +245,7 @@
   $_[0]{B};
 }
 
-=head3 root
+=head2 root
 
 Returns root node
 
@@ -251,7 +259,7 @@
   $self->{Root};
 }
 
-=head3 node_overfull
+=head2 node_overfull
 
 Returns if node is overfull
 
@@ -265,7 +273,7 @@
   $node->size > $self->B;
 }
 
-=head3 to_string
+=head2 to_string
 
 Returns your tree as formatted string.
 
@@ -279,7 +287,7 @@
   $_[0]->root->to_string;
 }
 
-=head3 to_dot
+=head2 to_dot
 
 Create Graphviz graph of your tree
 
@@ -297,7 +305,7 @@
 	return $dot;
 }
 
-=head3 to_jsfind
+=head2 to_jsfind
 
 Create xml index files for jsFind. This should be called after
 your B-Tree has been filled with data.
@@ -346,11 +354,11 @@
   $_[0] cmp $_[1];
 }
 
-=head3 _recode
+=head2 _recode
 
 This is internal function to recode charset.
 
-It will also try to decode HTML::Entities in data.
+It will also try to decode entities in data using L<HTML::Entities>.
 
 =cut
 
@@ -373,7 +381,7 @@
 
 #####################################################################
 
-=head2 jsFind::Node methods
+=head1 jsFind::Node methods
 
 Each node has C<k> key-data pairs, with C<B> <= C<k> <= C<2B>, and 
 each has C<k+1> subnodes, which might be null.
@@ -403,7 +411,7 @@
 my $DATA = 1;
 my $SUBNODES = 2;
 
-=head3 new
+=head2 new
 
 Create New node
 
@@ -423,7 +431,7 @@
   bless [@_] => $package;
 }
 
-=head3 locate_key
+=head2 locate_key
 
 Locate key in node using linear search. This should probably be replaced
 by binary search for better performance.
@@ -460,7 +468,7 @@
 }
 
 
-=head3 emptynode
+=head2 emptynode
 
 Creates new empty node
 
@@ -473,7 +481,7 @@
   new($_[0]);			# Pass package name, but not anything else.
 }
 
-=head3 is_empty
+=head2 is_empty
 
 Test if node is empty
 
@@ -487,7 +495,7 @@
   !defined($self) || $#$self < 0;
 }
 
-=head3 key
+=head2 key
 
 Return C<$i>th key from node
 
@@ -503,7 +511,7 @@
    $_[0]->[$KEYS][$_[1]];
 }
 
-=head3 data
+=head2 data
 
 Return C<$i>th data from node
 
@@ -516,7 +524,7 @@
   $self->[$DATA][$n];
 }
 
-=head3 kdp_replace
+=head2 kdp_replace
 
 Set key data pair for C<$i>th element in node
 
@@ -537,9 +545,13 @@
    $self->[$DATA][$n]];
 }
 
-=head3 kdp_insert
+=head2 kdp_insert
 
- # No return value.
+Insert key/data pair in tree
+
+  $node->kdp_insert("key value" => "data value");
+
+No return value.
 
 =cut
 
@@ -558,7 +570,7 @@
   splice(@{$self->[$SUBNODES]}, $where, 0, undef);
 }
 
-=head3 kdp_append
+=head2 kdp_append
 
 Adds new data keys and values to C<$i>th element in node
 
@@ -579,7 +591,7 @@
    $self->[$DATA][$n]];
 }
 
-=head3 subnode
+=head2 subnode
 
 Set new or return existing subnode
 
@@ -597,7 +609,7 @@
   $self->[$SUBNODES][$n];
 }
 
-=head3 is_leaf
+=head2 is_leaf
 
 Test if node is leaf
 
@@ -610,7 +622,7 @@
   ! defined $self->[$SUBNODES][0]; # undefined subnode means leaf node.
 }
 
-=head3 size
+=head2 size
 
 Return number of keys in the node
 
@@ -623,11 +635,12 @@
   return scalar(@{$self->[$KEYS]});
 }
 
-=head3 halves
+=head2 halves
+
+Split node into two halves so that keys C<0 .. $n-1> are in one node
+and keys C<$n+1 ... $size> are in the other.
 
- # Accept an index $n
- # Divide into two nodes so that keys 0 .. $n-1 are in one node
- # and keys $n+1 ... $size are in the other.
+  my ($left_node, $right_node, $kdp) = $node->halves($n);
 
 =cut
 
@@ -651,7 +664,7 @@
   ($self->new(@left), $self->new(@right), \@middle);
 }
 
-=head3 to_string
+=head2 to_string
 
 Dumps tree as string
 
@@ -702,7 +715,7 @@
 
 =end comment
 
-=head3 to_dot
+=head2 to_dot
 
 Recursivly walk nodes of tree
 
@@ -741,7 +754,7 @@
 	$dot;
 }
 
-=head3 to_xml
+=head2 to_xml
 
 Escape <, >, & and ", and to produce valid XML
 
@@ -760,7 +773,7 @@
 	return $d;
 }
 
-=head3 to_jsfind
+=head2 to_jsfind
 
 Create jsFind xml files