Item10009: a little more docco now

git-svn-id: http://svn.foswiki.org/trunk@12339 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

core/lib/Foswiki/Serialise.pm

@@ -5,30 +5,62 @@ use strict;
 use warnings;
 use Foswiki ();
 
+=begin TML
+
+---+ package Foswiki::Serialise
+
+API to allow structures to be serialised and de-serialized. This API will only return
+basic types like hashes and arrarys
+
+=cut
+
 #lets only load the serialiser once per execution
 our %serialisers = ();
 
 #should this really be a register/request?
 
+
+=begin TML
+
+---++ StaticMethod serialise( $session, $value, $style ) -> $cereal
+   * =$session= Foswiki Session object
+   * =$value= the perl object we're serializing (typically a ref/obj)
+   * =$style= serialization format
+
 #TODO: do we need to use Foswiki, or can we throw a Simple exception instead?
 #I think to be reusable we catually have to throw..
+
+=cut
+
 sub serialise {
     my $session = shift;
-    my $result  = shift;
+    my $value  = shift;
     my $style   = shift;
 
-    my $data = getSerialiser( $session, $style )->write( $session, $result );
-    return $data;
+    return getSerialiser( $session, $style )->write( $session, $value );
 }
 
-#TODO: ok, ugly, and incomplete
+
+=begin TML
+
+---++ StaticMethod deserialise( $session, $cereal, $style ) -> $data
+   * =$session= Foswiki Session object
+   * =$cereal= the perl object we're serializing (typically a ref/obj)
+   * =$style= serialization format
+
+#TODO: do we need to use Foswiki, or can we throw a Simple exception instead?
+#I think to be reusable we actually have to throw..
+
+#TODO: please work out how to add _some_ autodetection of format
+
+=cut
+
 sub deserialise {
     my $session = shift;
-    my $result  = shift;
+    my $cereal  = shift;
     my $style   = shift;
 
-    my $data = getSerialiser( $session, $style )->read( $session, $result );
-    return $data;
+    return getSerialiser( $session, $style )->read( $session, $cereal );
 }
 
 #in the event of trouble, return 'Simplified'

core/lib/Foswiki/Serialise/Embedded.pm

@@ -6,6 +6,8 @@
 
 This is __the__ on disk format serialiser and deserialise for TWiki and Foswiki topics legacy .txt format.
 
+__WARNING__ this is only for Foswiki::Meta objects.
+
 =cut
 
 package Foswiki::Serialise::Embedded;

core/lib/Foswiki/Serialise/Json.pm

@@ -4,7 +4,7 @@
 
 ---+ package Foswiki::Serialise::Json
 
-
+serialise from and to JSON
 
 =cut
 

core/lib/Foswiki/Serialise/Perl.pm

@@ -4,7 +4,9 @@
 
 ---+ package Foswiki::Serialise::Perl
 
-This is __the__ on disk format serialiser and deserialise for TWiki and Foswiki topics legacy .txt format.
+This is a Data::Dumper style
+
+#TODO: rename?
 
 =cut
 

core/lib/Foswiki/Serialise/Simplified.pm

@@ -4,7 +4,7 @@
 
 ---+ package Foswiki::Serialise::Simplified
 
-This is __the__ on disk format serialiser and deserialise for TWiki and Foswiki topics legacy .txt format.
+This is the style=perl serialiseation used by System.VarQUERY
 
 =cut