added documentation

2 files changed, 82 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 7196723..b295448 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,5 @@ inc/
 /META.yml
 /pm_to_blib
 /Makefile
+*~
+cover_db/
diff --git a/lib/PPIx/XPath.pm b/lib/PPIx/XPath.pm
index d4975e4..586236c 100644
--- a/lib/PPIx/XPath.pm
+++ b/lib/PPIx/XPath.pm
@@ -387,6 +387,86 @@ __END__
 
 PPIx::XPath - an XPath implementation for the PDOM
 
+=head1 SYNOPSIS
+
+  use PPI;
+  use PPI::XPath;
+  use Tree::XPathEngine;
+
+  my $pdom = PPI::Document->new('some_code.pl');
+  my $xpath = Tree::XPathEngine->new();
+  my @subs = $xpath->findnodes('//Statement-Sub',$pdom);
+  my @vars = $xpath->findnodes('//Token-Symbol',$pdom);
+
+Deprecated interface, backward-compatible with C<PPIx::XPath> version
+1:
+
+  use PPIx::XPath;
+
+  my $pxp  = PPIx::XPath->new("some_code.pl");
+  my @subs = $pxp->match("//Statement::Sub");
+  my $vars = $pxp->match("//Token::Symbol");
+
+=head1 DESCRIPTION
+
+This module augments L<PPI>'s classes with the methods required by
+L<Tree::XPathEngine>, allowing you to perform complex XPath matches
+against any PDOM tree.
+
+See L<Tree::XPathEngine> for details about its methods.
+
+=head2 Mapping the PDOM to the XPath data model
+
+=over 4
+
+=item *
+
+Each node in the PDOM is an element as seen by XPath
+
+=item *
+
+The name of the element is the class name of the node, minus the
+initial C<PPI::>, with C<::> replaced by C<->. That is:
+
+  ($xpath_name = substr($pdom_node->class,5)) =~ s/::/-/g;
+
+=item *
+
+Only "significant" nodes are seen by XPath
+
+=item *
+
+all scalar-valued accessors of PDOM nodes are visible as attributes
+
+=item *
+
+"here-docs" contents are I<not> mapped
+
+=back
+
+=head1 BUGS and LIMITATIONS
+
+=over 4
+
+=item *
+
+"here-docs" contents are I<not> mapped
+
+=item *
+
+node ordering is slow, because I could not find a way in PPI to
+compare two nodes for document order; suggestions are most welcome
+
+=back
+
+=head1 SEE ALSO
+
+L<PPI>
+
+L<Tree::XPathEngine>
+
+L<http://www.w3.org/TR/xpath> (the XPath specification)
+
 =head1 AUTHOR
 
 Dan Brook <cpan@broquaint.com> original author