Merge pull request #46 from libwww-perl/genio-puny-doc

Update the documentation for URI::_punycode

Author: karenetheridge

Changes

@@ -1,6 +1,7 @@
 Revision history for URI
 
 {{$NEXT}}
+    - Update documentation for URI::_punycode (GH Issue #45)
 
 1.72      2017-07-25
     - Convert the dist to Dist::Zilla for authoring.

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<[email protected]>> 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>[email protected]E<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