[Bps-public-commit] r15968 - in Prophet/trunk: .

[spang at bestpractical.com]

Author: spang
Date: Sat Sep 13 20:41:15 2008
New Revision: 15968

Modified:
   Prophet/trunk/   (props changed)
   Prophet/trunk/lib/Prophet/Change.pm
   Prophet/trunk/lib/Prophet/ChangeSet.pm

Log:
 r49799 at loki:  spang | 2008-09-13 20:38:09 -0400
 cleanups and moar pod while we're at it


Modified: Prophet/trunk/lib/Prophet/Change.pm
==============================================================================
--- Prophet/trunk/lib/Prophet/Change.pm	(original)
+++ Prophet/trunk/lib/Prophet/Change.pm	Sat Sep 13 20:41:15 2008
@@ -58,19 +58,31 @@
 
 =head2 record_uuid
 
-The UUID of the record being changed
+The UUID of the record being changed.
 
 =head2 change_type
 
-One of add_file, add_dir, update_file, delete
+One of C<add_file>, C<add_dir>, C<update_file>, C<delete>.
+
+=head2 is_resolution
+
+A boolean value specifying whether this change represents a conflict
+resolution or not.
 
 =head2 prop_changes [\@PROPCHANGES]
 
-Returns a list of L<Prophet::PropChange/> associated with this Change. Takes an optional arrayref to fully replace the set of propcahnges
+Returns a list of L<Prophet::PropChange/> associated with this Change. Takes an
+optional arrayref to fully replace the set of propchanges.
 
-=cut
+=head2 has_prop_changes
+
+Returns true if this change contains any L</Prophet::PropChange>s and false
+if it doesn't.
 
-=head2 new_from_conflict( $conflict )
+=head2 new_from_conflict $conflict
+
+Takes a L<Prophet::Conflict> object and creates a Prophet::Change object
+representing the conflict resolution.
 
 =cut
 
@@ -106,9 +118,16 @@
     $self->_add_prop_change($change);
 }
 
+=head2 as_hash
+
+Returns a reference to a representation of this change as a hash.
+
+=cut
+
 sub as_hash {
     my $self  = shift;
     my $props = {};
+
     for my $pc ( $self->prop_changes ) {
         $props->{ $pc->name } = { old_value => $pc->old_value, new_value => $pc->new_value };
     }
@@ -145,6 +164,18 @@
 
 }
 
+=head2 new_from_hashref HASHREF
+
+Takes a reference to a hash representation of a change (such as is
+returned by L</as_hash> or serialized json) and returns a new
+Prophet::Change representation of it.
+
+This method should be invoked as a class method, not an object method.
+
+For example:
+C<Prophet::Change-E<gt>new_from_hashref($ref_to_change_hash)>
+
+=cut
 
 sub new_from_hashref {
     my $class   = shift;

Modified: Prophet/trunk/lib/Prophet/ChangeSet.pm
==============================================================================
--- Prophet/trunk/lib/Prophet/ChangeSet.pm	(original)
+++ Prophet/trunk/lib/Prophet/ChangeSet.pm	Sat Sep 13 20:41:15 2008
@@ -70,49 +70,63 @@
 
 =head1 DESCRIPTION
 
-This class represents a single, atomic Prophet database update. It tracks some metadata about the changeset it self and contains a list of L<Prophet::Change> entries which describe the actual records created, updated and deleted.
-
-=cut
+This class represents a single, atomic Prophet database update. It tracks some
+metadata about the changeset itself and contains a list of L<Prophet::Change>
+entries which describe the actual records created, updated and deleted.
 
 =head1 METHODS
 
-=cut
-
 =head2 new
 
 Instantiate a new, empty L<Prophet::ChangeSet> object.
 
-=cut
+=head2 creator
+
+A string representing who created this changeset.
+
+=head2 created
+
+A string representing the ISO 8601 date and time when this changeset
+was created (UTC).
 
 =head2 sequence_no
 
-The changeset's sequence number (In subversion terms, revision #) on the replica sending us the changeset
+The changeset's sequence number (in subversion terms, revision #) on the
+replica sending us the changeset.
 
 =head2 source_uuid
 
-The uuid of the replica sending us the change
+The uuid of the replica sending us the change.
 
 =head2 original_source_uuid
 
-The uuid of the replica where the change was authored
+The uuid of the replica where the change was authored.
 
 =head2 original_sequence_no
 
-The changeset's sequence number (In subversion terms, revision #) on the replica where the change was originally created
+The changeset's sequence number (in subversion terms, revision #) on the
+replica where the change was originally created.
 
 =head2 is_nullification
 
-Currently unused
+A boolean value specifying whether this is a nullification changeset or not.
 
 =head2 is_resolution
 
-Currently unused
+A boolean value specifying whether this is a conflict resolution changeset
+or not.
 
-=cut
+=head2 changes
+
+Returns an array of all the changes in the current changeset.
+
+=head2 has_changes
+
+Returns true if this changeset has any changes.
 
 =head2 add_change { change => L<Prophet::Change> }
 
-Add a new change, L<$args{'change'}> to this changeset.
+Adds a new change, L<$args{'change'}> to this changeset.
 
 =cut
 
@@ -123,32 +137,42 @@
 
 }
 
-=head2 changes
-
-Return an array of all the changes in the current changeset.
-
-=cut
+our @SERIALIZE_PROPS
+    = (qw(creator created sequence_no source_uuid original_source_uuid original_sequence_no is_nullification is_resolution));
 
-=head2 has_changes
+=head2 as_hash
 
-Returns true if this changeset has any changes
+Returns a reference to a representation of this changeset as a hash, containing
+all the properties in the package variable C<@SERIALIZE_PROPS>, as well as a
+C<changes> key containing hash representations of each change in the changeset,
+keyed on UUID.
 
 =cut
 
-our @SERIALIZE_PROPS
-    = (qw(creator created sequence_no source_uuid original_source_uuid original_sequence_no is_nullification is_resolution));
-
 sub as_hash {
     my $self = shift;
     my $as_hash = { map { $_ => $self->$_() } @SERIALIZE_PROPS };
 
     for my $change ( $self->changes ) {
-
         $as_hash->{changes}->{ $change->record_uuid } = $change->as_hash;
     }
+
     return $as_hash;
 }
 
+=head2 new_from_hashref HASHREF
+
+Takes a reference to a hash representation of a changeset (such as is
+returned by L</as_hash> or serialized json) and returns a new
+Prophet::ChangeSet representation of it.
+
+Should be invoked as a class method, not an object method.
+
+For example:
+C<Prophet::ChangeSet-E<gt>new_from_hashref($ref_to_changeset_hash)>
+
+=cut
+
 sub new_from_hashref {
     my $class   = shift;
     my $hashref = shift;