Persister docs (#70)

* Detail documentation for the Persister API

Writing my own persister, I ran into some unclarities in the docs,
in combination with unexpected behaviour from the DBI persister.

* Fix the DBI persister to adhere to the protocol

lib/Workflow/Persister.pm

@@ -200,20 +200,25 @@ Persister. Since this is a SUPER class.
 Generate an ID for the workflow, serialize the workflow data (ID and
 state) and set the ID in the workflow.
 
+Returns the ID for the workflow.
+
 =head3 update_workflow( $workflow )
 
 Stub that warns that the method should be overwritten in the derived
 Persister. Since this is a SUPER class.
 
 Update the workflow state.
 
+Returns nothing.
+
 =head3 fetch_workflow( $workflow_id )
 
 Stub that warns that the method should be overwritten in the derived
 Persister. Since this is a SUPER class.
 
 Retrieve the workflow data corresponding to C<$workflow_id>. It not
-found return undef, if found return a hashref with the data.
+found return undef, if found return a hashref with at least the keys
+C<state> and C<last_update> (a L<DateTime> instance).
 
 =head3 create_history( $workflow, @history )
 
@@ -222,6 +227,9 @@ Persister. Since this is a SUPER class.
 
 Serialize all objects in C<@history> for later retrieval.
 
+Returns C<@history>, the list of history objects, with the history
+C<id> and C<saved> values set according to the saved results.
+
 =head3 fetch_history( $workflow )
 
 Stub that warns that the method should be overwritten in the derived

lib/Workflow/Persister/DBI.pm

@@ -240,6 +240,8 @@ sub create_workflow {
         }
     }
     $sth->finish;
+
+    $wf->id($id);
     return $id;
 }
 

lib/Workflow/Persister/File.pm

@@ -51,6 +51,7 @@ sub create_workflow {
     my $full_history_path = $self->_get_history_path($wf);
     mkdir( $full_history_path, 0777 )
         || persist_error "Cannot create history dir '$full_history_path': $!";
+
     return $wf_id;
 }