A minimial documentation

diff --git a/Makefile.PL b/Makefile.PL
index 35a30594bdf3a58a971dd4ca2b1bbb2e248acf94..248c76f9d94fd3cca50e3c0acd1fb9dbed59a3b2 100644 (file)
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -60,7 +60,7 @@ WriteMakefile(
  AUTHOR           => 'Vincent Pit <perl@profvince.com>',
  LICENSE          => 'perl',
  VERSION_FROM     => $file,
-# ABSTRACT_FROM    => $file,
+ ABSTRACT_FROM    => $file,
  PL_FILES         => {},
  PREREQ_PM        => \%PREREQ_PM,
  MIN_PERL_VERSION => 5.010,

diff --git a/lib/Sub/Op.pm b/lib/Sub/Op.pm
index 94cfe955a538c5d59d7b7b72c8a8e7619570bc9a..dbcdcd2a46ff0582efb085169afdacbc92a50198 100644 (file)
--- a/lib/Sub/Op.pm
+++ b/lib/Sub/Op.pm
@@ -5,6 +5,16 @@ use 5.010;
 use strict;
 use warnings;
 
+=head1 NAME
+
+Sub::Op - Install subroutines as opcodes.
+
+=head1 VERSION
+
+Version 0.01
+
+=cut
+
 our ($VERSION, @ISA);
 
 sub dl_load_flags { 0x01 }
@@ -16,6 +26,74 @@ BEGIN {
  __PACKAGE__->bootstrap($VERSION);
 }
 
+=head1 SYNOPSIS
+
+In your XS file :
+
+    #include "sub_op.h"
+
+    STATIC OP *scalar_util_reftype(pTHX) {
+     dSP;
+     dMARK;
+     SV *sv = POPs;
+     if (SvMAGICAL(sv))
+      mg_get(sv);
+     if (SvROK(sv))
+      PUSHs(sv_reftype(SvRV(sv), 0));
+     else
+      PUSHs(&PL_sv_undef);
+     RETURN;
+    }
+
+    MODULE = Scalar::Util::Ops       PACKAGE = Scalar::Util::Ops
+
+    BOOT:
+    {
+     sub_op_keyword k;
+     k.name  = "reftype";
+     k.len   = sizeof("reftype")-1;
+     k.check = 0;
+     k.pp    = scalar_util_reftype;
+     sub_op_register(aTHX_ &k);
+    }
+
+In your Perl module file :
+
+    package Scalar::Util::Ops;
+
+    use strict;
+    use warnings;
+
+    our ($VERSION, @ISA);
+
+    use Sub::Op; # Before loading our own shared library
+
+    BEGIN {
+     $VERSION = '0.01';
+     require DynaLoader;
+     push @ISA, 'DynaLoader';
+     __PACKAGE__->bootstrap($VERSION);
+    }
+
+    sub import   { Sub::Op::enable(reftype => scalar caller) }
+
+    sub unimport { Sub::Op::disable(reftype => scalar caller) }
+
+    1;
+
+In your F<Makefile.PL> :
+
+    use ExtUtils::Depends;
+
+    my $ed = ExtUtils::Depends->new('Scalar::Util::Ops' => 'Sub::Op');
+
+    WriteMakefile(
+     $ed->get_makefile_vars,
+     ...
+    );
+
+=cut
+
 use B::Hooks::EndOfScope;
 use Variable::Magic 0.08;
 
@@ -198,4 +276,46 @@ sub _inject {
 
 BEGIN { _monkeypatch() }
 
+=head1 DEPENDENCIES
+
+L<perl> 5.10.
+
+L<Variable::Magic>, L<B::Hooks::EndOfScope>.
+
+L<ExtUtils::Depends>.
+
+=head1 SEE ALSO
+
+L<subs::auto>.
+
+L<B::Hooks::OP::Check::EntersubForCV>.
+
+=head1 AUTHOR
+
+Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
+
+You can contact me by mail or on C<irc.perl.org> (vincent).
+
+=head1 BUGS
+
+Please report any bugs or feature requests to C<bug-sub-op at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Op>.
+I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
+
+=head1 SUPPORT
+
+You can find documentation for this module with the perldoc command.
+
+    perldoc Sub::Op
+
+Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Sub-Op>.
+
+=head1 COPYRIGHT & LICENSE
+
+Copyright 2010 Vincent Pit, all rights reserved.
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
+
 1; # End of Sub::Op