Fix innaccuracy in hooks examples.

Add PHPDoc blocks to sample code.

`creating`, `updating`, and `saving` must always return `$data` array.

Author: Xint0-elab

editor-events.md

@@ -13,18 +13,40 @@ Create action has the following event hooks:
 To use the event hook, just add the methods on your editor class.
 
 ```php
+/**
+ * Event hook that is fired before creating a new record.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model Empty model instance.
+ * @param array $data Attribute values array received from Editor.
+ * @return array The updated attribute values array.
+ */
 public function creating(Model $model, array $data)
 {
-    // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not required
-    // to return the $model.
-    // In version 1.8.0+ the hook must return the $model instance:
-    return $model;
+    // Code can change the attribute values array before saving data to the
+    // database.
+    // Can be used to initialize values on new model.
+
+    // Since arrays are copied when passed by value, the function must return
+    // the updated $data array
+    return $data;
 }
 
+/**
+ * Event hook that is fired after a new record is created.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model The newly created model.
+ * @param array $data Attribute values array received from `creating` or
+ *   `saving` hook.
+ * @return \Illuminate\Database\Eloquent\Model Since version 1.8.0 it must
+ *   return the $model.
+ */
 public function created(Model $model, array $data)
 {
-    // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not required
-    // to return the $model.
+    // Can be used to mutate state of newly created model that is returned to
+    // Editor.
+
+    // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not
+    // required to return the $model.
     // In version 1.8.0+ the hook must return the $model instance:
     return $model;
 }
@@ -35,37 +57,94 @@ public function created(Model $model, array $data)
 
 Edit action has the following event hooks:
 
-- `updating` event hook that is fired before updating a new record.
+- `updating` event hook that is fired before updating an existing record.
 - `updated` event hook that is fired after the record was updated.
 
 To use the event hook, just add the methods on your editor class.
 
 ```php
+/**
+ * Event hook that is fired before updating an existing record.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model Model instance retrived
+ *  retrived from database.
+ * @param array $data Attribute values array received from Editor.
+ * @return array The updated attribute values array.
+ */
 public function updating(Model $model, array $data) {
-    // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not required
-    // to return the $model.
-    // In version 1.8.0+ the hook must return the $model:
-    return $model;
+    // Can be used to modify the attribute values received from Editor before
+    // applying changes to model.
+
+    // Since arrays are copied when passed by value, the function must return
+    // the updated $data array
+    return $data;
 }
 
+/**
+ * Event hook that is fired after the record was updated.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model Updated model instance.
+ * @param array $data Attribute values array received from `updating` or
+ *   `saving` hook.
+ * @return \Illuminate\Database\Eloquent\Model Since version 1.8.0 it must
+ *   return the $model.
+ */
 public function updated(Model $model, array $data) {
+    // Can be used to mutate state of updated model that is returned to Editor.
+
     // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not required
     // to return the $model.
     // In version 1.8.0+ the hook must return the $model instance:
     return $model;
 }
 ```
 
-<a name="saved-event"></a>
-## Saved event
+<a name="save-events"></a>
+## Save events
 
-In addition to create and edit events, the `saved` event hook is called after `created` and `saved`.
+In addition to create and edit events, the following save event hooks are available:
+
+- `saving` event hook that is fired after `creating` and `updating` events, but
+    before the model is saved to the database.
+- `saved` event hook that is fired after `created` and `updated` events.
 
 To use the event hook, just add the method on your editor class:
 
 ```php
+/**
+ * Event hook that is fired after `creating` and `updating` hooks, but before
+ * the model is saved to the database.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model Empty model when creating;
+ *   Original model when updating.
+ * @param array $data Attribute values array received from `creating` or
+ *   `updating` event hook.
+ * @return array The updated attribute values array.
+ */
+public function saving(Model $model, array $data)
+{
+    // The event hook can be used to modify the $data array that is used to
+    // create or update the record.
+
+    // Since arrays are copied when passed by value, the function must return
+    // the updated $data array
+    return $data;
+}
+
+/**
+ * Event hook that is fired after `created` and `updated` events.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model The new model when
+ *   creating; the updated model when updating.
+ * @param array $data Attribute values array received from `creating`,
+ *   `updating`, or `saving`.
+ * @return \Illuminate\Database\Eloquent\Model Since version 1.8.0 it must
+ *   return the $model.
+ */
 public function saved(Model $model, array $data)
 {
+    // Can be used to mutate state of updated model that is returned to Editor.
+
     // Prior to version 1.8.0 of Laravel DataTables Editor the hook was not required
     // to return the $model.
     // In version 1.8.0+ the hook must return the $model instance:
@@ -84,15 +163,31 @@ Remove action has the following event hooks:
 To use the event hook, just add the methods on your editor class.
 
 ```php
+/**
+ * Event hook that is fired before deleting an existing record.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model The original model
+ *   retrieved from database.
+ * @param array $data Attribute values array received from Editor.
+ * @return void
+ */
 public function deleting(Model $model, array $data) {
     // Record still exists in database. Code can be used to delete records from
     // child tables that don't specify cascade deletes on the foreign key
     // definition.
 }
 
+/**
+ * Event hook that is fired after deleting the record from database.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model The original model
+ *   retrieved from database.
+ * @param array $data Attribute values array received from Editor.
+ * @return void
+ */
 public function deleted(Model $model, array $data) {
     // Record no longer exists in database, but $model instance still contains
-    // data as it was before deleting. Any instance state mutation will be
-    // preserved and returned in the 'data' array of the response.
+    // data as it was before deleting. Any changes to the $model instance will
+    // be returned to Editor.
 }
 ```