[Opensrf-commits] r1791 - in trunk/src/perl: lib/OpenSRF/Utils t (sboyette)

[svn at svn.open-ils.org]

Author: sboyette
Date: 2009-09-15 12:39:33 -0400 (Tue, 15 Sep 2009)
New Revision: 1791

Modified:
   trunk/src/perl/lib/OpenSRF/Utils/JSON.pm
   trunk/src/perl/t/09-Utils-JSON.t
Log:
POD/docs cleanup

Modified: trunk/src/perl/lib/OpenSRF/Utils/JSON.pm
===================================================================
--- trunk/src/perl/lib/OpenSRF/Utils/JSON.pm	2009-09-15 16:19:48 UTC (rev 1790)
+++ trunk/src/perl/lib/OpenSRF/Utils/JSON.pm	2009-09-15 16:39:33 UTC (rev 1791)
@@ -97,7 +97,8 @@
 
 =head2 rawJSON2perl
 
-Intermediate routine called by L</JSON2Perl>.
+Performs actual JSON -> data transformation, before
+L</JSONObject2Perl> is called.
 
 =cut
 
@@ -110,7 +111,8 @@
 
 =head2 rawPerl2JSON
 
-Intermediate routine used by L</Perl2JSON>.
+Performs actual data -> JSON transformation, after L</perl2JSONObject>
+has been called.
 
 =cut
 
@@ -124,8 +126,15 @@
 
 =head2 JSONObject2Perl
 
-Intermediate routine called by L</rawJSON2perl>.
+Routine called by L</JSON2perl> after L</rawJSON2perl> is called.
 
+At this stage, the JSON string will have been vivified as data. This
+routine's job is to turn it back into an OpenSRF system object of some
+sort, if possible.
+
+If it's not possible, the original data (structure), or one very much
+like it will be returned.
+
 =cut
 
 sub JSONObject2Perl {
@@ -174,6 +183,22 @@
 
 =head2 perl2JSONObject
 
+Routine called by L</perl2JSON> before L</rawPerl2JSON> is called.
+
+For OpenSRF system objects which have had hints about their classes
+stowed via L</register_class_hint>, this routine acts as a wrapper,
+encapsulating the incoming object in metadata about itself. It is not
+unlike the process of encoding IP datagrams.
+
+The only metadata encoded at the moment is the class hint, which is
+used to reinflate the data as an object of the appropriate type in the
+L</JSONObject2perl> routine.
+
+Other forms of data more-or-less come out as they went in, although
+C<CODE> or C<SCALAR> references will return what looks like an OpenSRF
+packet, but with a class hint of their reference type and an C<undef>
+payload.
+
 =cut
 
 sub perl2JSONObject {
@@ -204,6 +229,9 @@
 
 =head2 lookup_class
 
+Given a class hint, returns the classname matching it. Returns undef
+on failure.
+
 =cut
 
 sub lookup_class {
@@ -219,6 +247,9 @@
 
 =head2 lookup_hint
 
+Given a classname, returns the class hint matching it. Returns undef
+on failure.
+
 =cut
 
 sub lookup_hint {

Modified: trunk/src/perl/t/09-Utils-JSON.t
===================================================================
--- trunk/src/perl/t/09-Utils-JSON.t	2009-09-15 16:19:48 UTC (rev 1790)
+++ trunk/src/perl/t/09-Utils-JSON.t	2009-09-15 16:39:33 UTC (rev 1791)
@@ -67,7 +67,7 @@
 is_deeply (OpenSRF::Utils::JSON->rawJSON2perl(OpenSRF::Utils::JSON->rawPerl2JSON($struct)),
            [ { foo => 'bar' }, 'baz', 'quux', 'x']);
 is (OpenSRF::Utils::JSON->rawJSON2perl(), undef, "Null argument");
-is (OpenSRF::Utils::JSON->rawJSON2perl(''), undef, "Null string as argument");
+is (OpenSRF::Utils::JSON->rawJSON2perl(''), undef, "Null string as argument"); # note inconsistency with above
 
 
 #