Update the documentation for URI::_punycode to show better examplesgenio-puny-doc

to fix GH Issue #45.

Standardized the documentation a bit as well by using head2 entries
instead of over and item. This allows metacpan and the like to
auto-generate a Table of Contents a bit more easily and makes direct
links to sections/functions a bit simpler.

The synopsis should be directly runnable now if someone were to
copy and paste it to test.

1 files changed, 41 insertions, 27 deletions

diff --git a/lib/URI/_punycode.pm b/lib/URI/_punycode.pm
index 89233de..ca5ebf2 100644
--- a/lib/URI/_punycode.pm
+++ b/lib/URI/_punycode.pm
@@ -147,58 +147,72 @@ sub min {
 1;
 __END__
 
+=encoding utf8
+
 =head1 NAME
 
 URI::_punycode - encodes Unicode string in Punycode
 
 =head1 SYNOPSIS
 
-  use URI::_punycode;
-  $punycode = encode_punycode($unicode);
-  $unicode  = decode_punycode($punycode);
+  use strict;
+  use warnings;
+  use utf8;
 
-=head1 DESCRIPTION
+  use URI::_punycode qw(encode_punycode decode_punycode);
 
-URI::_punycode is a module to encode / decode Unicode strings into
-Punycode, an efficient encoding of Unicode for use with IDNA.
+  # encode a unicode string
+  my $punycode = encode_punycode('http://☃.net'); # http://.net-xc8g
+  $punycode = encode_punycode('bücher'); # bcher-kva
+  $punycode = encode_punycode('他们为什么不说中文'); # ihqwcrb4cv8a8dqg056pqjye
 
-This module requires Perl 5.6.0 or over to handle UTF8 flagged Unicode
-strings.
+  # decode a punycode string back into a unicode string
+  my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net
+  $unicode = decode_punycode('bcher-kva'); # bücher
+  $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文
 
-=head1 FUNCTIONS
+=head1 DESCRIPTION
 
-This module exports following functions by default.
+L<URI::_punycode> is a module to encode / decode Unicode strings into
+L<Punycode|https://tools.ietf.org/html/rfc3492>, an efficient
+encoding of Unicode for use with L<IDNA|https://tools.ietf.org/html/rfc5890>.
 
-=over 4
+=head1 FUNCTIONS
+
+All functions throw exceptions on failure. You can C<catch> them with
+L<Syntax::Keyword::Try> or L<Try::Tiny>. The following functions are exported
+by default.
 
-=item encode_punycode
+=head2 encode_punycode
 
-  $punycode = encode_punycode($unicode);
+  my $punycode = encode_punycode('http://☃.net');  # http://.net-xc8g
+  $punycode = encode_punycode('bücher'); # bcher-kva
+  $punycode = encode_punycode('他们为什么不说中文') # ihqwcrb4cv8a8dqg056pqjye
 
-takes Unicode string (UTF8-flagged variable) and returns Punycode
+Takes a Unicode string (UTF8-flagged variable) and returns a Punycode
 encoding for it.
 
-=item decode_punycode
+=head2 decode_punycode
 
-  $unicode = decode_punycode($punycode)
+  my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net
+  $unicode = decode_punycode('bcher-kva'); # bücher
+  $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文
 
-takes Punycode encoding and returns original Unicode string.
+Takes a Punycode encoding and returns original Unicode string.
 
-=back
+=head1 AUTHOR
 
-These functions throw exceptions on failure. You can catch 'em via
-C<eval>.
+Tatsuhiko Miyagawa <F<miyagawa@bulknews.net>> is the author of
+L<IDNA::Punycode> which was the basis for this module.
 
-=head1 AUTHOR
+=head1 SEE ALSO
+
+L<IDNA::Punycode>, L<RFC 3492|https://tools.ietf.org/html/rfc3492>,
+L<RFC 5891|https://tools.ietf.org/html/rfc5891>
 
-Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt> is the author of
-IDNA::Punycode v0.02 which was the basis for this module.
+=head1 COPYRIGHT AND LICENSE
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
-=head1 SEE ALSO
-
-L<IDNA::Punycode>, RFC 3492
-
 =cut