8 files changed, 628 insertions, 27 deletions

diff --git a/lib/Config/HAProxy.pm b/lib/Config/HAProxy.pm
index 7938bcb..f99bf33 100644
--- a/lib/Config/HAProxy.pm
+++ b/lib/Config/HAProxy.pm
@@ -179,16 +179,16 @@ sub save {
     close($fh);
     
     my $sb = stat($self->filename);
     $self->backup;
     rename($tempfile, $self->filename)
         or croak "can't rename $tempfile to ".$self->tempfile.": $!";
-    # This will fail unless we are root, let it be so.
-    chown $sb->uid, $sb->gid, $self->filename;
     # This will succeed: we've created the file, so we're owning it.
     chmod $sb->mode & 0777, $self->filename;
+    # This will fail unless we are root, let it be so.
+    chown $sb->uid, $sb->gid, $self->filename;
     
     $self->tree->clear_dirty
 }
 
 sub backup_name {
     my $self = shift;
@@ -212,63 +212,122 @@ sub backup {
 
 1;      
 __END__
 
 =head1 NAME
 
-Config::HAProxy - HAProxy configuration file
+Config::HAProxy - Parser for HAProxy configuration file
 
 =head1 SYNOPSIS
 
-use Config::HAProxy;
-$cfg = new Config::HAProxy($filename);
-$cfg->parse;
+    use Config::HAProxy;
+    $cfg = new Config::HAProxy($filename);
+    $cfg->parse;
 
-$name = $cfg->filename;
+    $name = $cfg->filename;
 
-@frontends = $cfg->select(name => 'frontend');
+    @frontends = $cfg->select(name => 'frontend');
 
-$itr = $cfg->iterator(inorder => 1);
-while (defined($node = $itr->next)) {
-    # do something with $node
-}
+    $itr = $cfg->iterator(inorder => 1);
+    while (defined($node = $itr->next)) {
+        # do something with $node
+    }
 
-$cfg->save;
+    $cfg->save;
 
-$cfg->write($file_or_handle);
+    $cfg->write($file_or_handle);
 
-$cfg->backup;
-$name = $self->backup_name;
+    $cfg->backup;
+    $name = $self->backup_name;
 
-$cfg->reset;
-$cfg->push($node);
-$node = $cfg->pop;
-$node = $cfg->tos;
-$node = $cfg->tree;
+    $cfg->reset;
+    $cfg->push($node);
+    $node = $cfg->pop;
+    $node = $cfg->tos;
+    $node = $cfg->tree;
 
 =head1 DESCRIPTION
 
-FIXME
+The B<Config::HAProxy> class is a parser that converts the B<HAProxy>
+configuration file to a parse tree and provides methods for various
+operations on this tree, such as: searching, modifying and saving it
+to a file.
+
+An object of this class contains a I<parse tree> representing the
+configuration read from the file (or created from scratch). Nodes in the
+tree can be of four distinct classes:
+
+=over 4
+
+=item Empty    
+
+Represents an empty line.
+    
+=item Comment
+
+Represents a comment line.
+    
+=item Statement
+
+Represents a simple statement.    
+
+=item Section
+
+A container, representing a C<compound statement>, i.e. a statement that
+contains multiple sub-statements. Compound statements are: B<global>,
+B<defaults>, B<frontend>, and B<backend>.    
+
+=back
+
+In addition to these four classes, a special class B<Root> is provided, which
+represents the topmost node in the parse tree (i.e. the parent of other nodes).
+
+A set of attributes is associated with each node. Among these, the B<orig>
+attribute contains the original line from the configuration file that triggered
+creation of this node, and B<locus> contains the location of this line (or
+lines, for sections) in the configuration file (as a B<Text::Locus>) object.
+
+These two attributes are meaningful for all nodes. For statement nodes (simple
+statements and sections) the B<kw> attribute contains the statement I<keyword>,
+and the B<argv> attribute - its arguments. For example, the statement
+
+    server localhost 127.0.0.1:8080
+
+is represented by a node of class B<Config::HAProxy::Node::Statement>, with
+C<server> as B<kw> and list (C<localhost>, C<127.0.0.1:8080>) as B<argv>.
+
+Additionally, section nodes provide methods for accessing their subtrees.
+
+For a detailed description of the node class and its methods, please refer to
+B<Config::HAProxy::Node>.    
     
 =head1 CONSTRUCTOR
 
     $cfg = new Config::HAProxy($filename);
 
 Creates and returns a new object for manipulating the HAProxy configuration.
 Optional B<$filename> specifies the name of the file to read configuration
 from. It defaults to F</etc/haproxy/haproxy.cfg>.
 
-=head1 THE PARSE TREE
+=head2 filename
+
+    $s = $cfg->filename;
+
+Returns the configuration file name given when creating the object.
+    
+=head1 PARSING
 
 =head2 parse
 
     $cfg->parse;
 
 Reads and parses the configuration file. Croaks if the file does not exist.
+Returns B<$cfg>.    
 
-
+=head1 BUILDING THE PARSE TREE
+    
 =head2 reset
 
     $cfg->reset;
 
 Clears the parse tree.
 
@@ -302,13 +361,13 @@ Returns the last node in the tree.
 =head1 SAVING
 
 =head2 save
 
     $cfg->save;
 
-Saves the configuration file.
+Saves the parse tree in the configuration file.
 
 =head2 write
 
     $cfg->write($file, %hash);
 
 Writes configuration to the named file or file handle. If B<$file> is the
@@ -324,6 +383,37 @@ Arguments with B<$i> greater than or equal to B<@tabstop> are appended to
 the resulting output, preserving their original offsets.    
 
 Normally, comments retain their original indentation. However, if the
 key B<reintent_comments> is present, and its value is evaluated as true,
 then comments are reindented following the rules described above.    
 
+=head1 SEE ALSO
+
+B<Config::HAProxy::Node>,
+B<Config::HAProxy::Node::Section>,    
+B<Config::HAProxy::Node::Statement>,