| Subject: | Documentation of Load() is sub-optimal |
The documentation of the Load() subroutine needs improvement. The patch attached (a) changes the name of a variable used in the example to make it more self-documenting and (b) provides an example of the return value in scalar context.
Please review.
Thank you very much.
Jim Keenan
| Subject: | 0001-Improve-documentation-for-Load.patch |
From 67fe2be431e584bc645c061fa7e3571ec7b62db7 Mon Sep 17 00:00:00 2001
From: James E Keenan <jkeenan@cpan.org>
Date: Sat, 2 Nov 2013 10:03:49 -0400
Subject: [PATCH] Improve documentation for Load().
Change name of variable used in example to make it more self-documenting.
Provide example and explanation of return value in scalar context.
---
lib/YAML/Tiny.pm | 14 +++++++++++---
1 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/lib/YAML/Tiny.pm b/lib/YAML/Tiny.pm
index b92286f..d6c06bf 100644
--- a/lib/YAML/Tiny.pm
+++ b/lib/YAML/Tiny.pm
@@ -964,15 +964,23 @@ Dies on any error.
=head2 Load
- my @documents = Load(string-containing-a-YAML-stream);
+ my @data_structures = Load(string-containing-a-YAML-stream);
Turn YAML into Perl data. This is the opposite of Dump.
Just like L<Storable>'s thaw() function or the eval() function in relation
to L<Data::Dumper>.
-It parses a character string containing a valid YAML stream into a list of Perl data
-structures. Be sure to decode it correctly if the string came from a file or socket.
+It parses a character string containing a valid YAML stream into a list of
+Perl data structures representing the individual YAML documents. Be sure to
+decode the character string correctly if the string came from a file or
+socket.
+
+ my $last_data_structure = Load(string-containing-a-YAML-stream);
+
+For consistency with YAML.pm, when Load is called in scalar context, it
+returns the data structure corresponding to the last of the YAML documents
+found in the input stream.
Dies on any error.
--
1.6.3.2