docs

1 files changed, 86 insertions, 0 deletions

diff --git a/lib/smartmatch.pm b/lib/smartmatch.pm
index 071e4ea..c7b67f6 100644
--- a/lib/smartmatch.pm
+++ b/lib/smartmatch.pm
@@ -18,6 +18,39 @@ __PACKAGE__->bootstrap(
         ? ${ $smartmatch::{VERSION} } : (),
 );
 
+=head1 SYNOPSIS
+
+  1 ~~ 2; # false
+  {
+      use smartmatch sub { 1 };
+      1 ~~ 2; # true
+
+      no smartmatch;
+      1 ~~ 2; # false
+
+      use smartmatch 'custom';
+      1 ~~ 2; # smartmatch::engine::custom::match(1, 2)
+  }
+  1 ~~ 2; # false
+
+=head1 DESCRIPTION
+
+NOTE: This module is still experimental, and the API may change at any point.
+You have been warned!
+
+This module allows you to override the behavior of the smart match operator
+(C<~~>). C<use smartmatch $matcher> hooks into the compiler to replace the
+smartmatch opcode with a call to a custom subroutine, specified either as a
+coderef or as a string, which will have C<smartmatch::engine::> prepended to it
+and used as the name of a package in which to find a subroutine named C<match>.
+The subroutine will be called with two arguments, the values on the left and
+right sides of the smart match operator, and should return the result.
+
+This module is lexically scoped, and you can call C<no smartmatch> to restore
+the core perl smart matching behavior.
+
+=cut
+
 sub import {
     my $package = shift;
     my ($cb) = @_;
@@ -36,4 +69,57 @@ sub unimport {
     smartmatch::unregister();
 }
 
+=head1 BUGS
+
+No known bugs.
+
+Please report any bugs through RT: email
+C<bug-smartmatch at rt.cpan.org>, or browse to
+L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=smartmatch>.
+
+=head1 SEE ALSO
+
+L<perlsyn/"Smart matching in detail">
+
+L<smartmatch::engine::core>
+
+=head1 SUPPORT
+
+You can find this documentation for this module with the perldoc command.
+
+    perldoc smartmatch
+
+You can also look for information at:
+
+=over 4
+
+=item * AnnoCPAN: Annotated CPAN documentation
+
+L<http://annocpan.org/dist/smartmatch>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/smartmatch>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=smartmatch>
+
+=item * Search CPAN
+
+L<http://search.cpan.org/dist/smartmatch>
+
+=back
+
+=begin Pod::Coverage
+
+import
+unimport
+register
+unregister
+
+=end Pod::Coverage
+
+=cut
+
 1;