Update Soft Delete trait docs

database/traits.md

@@ -526,7 +526,9 @@ You can also create custom validation rules the [same way](../services/validatio
 
 ## Soft deleting
 
-When soft deleting a model, it is not actually removed from your database. Instead, a `deleted_at` timestamp is set on the record. To enable soft deletes for a model, apply the `Winter\Storm\Database\Traits\SoftDelete` trait to the model and add the deleted_at column to your `$dates` property:
+Soft deleting allows for models to "act" as being deleted whilst still remaining in the database. Instead of removing a model record from the database on delete, a `deleted_at` timestamp is set on the record which, by default, will hide the record from any database query results.
+
+To enable soft deleting for a model, apply the `Winter\Storm\Database\Traits\SoftDelete` trait to the model and add the `deleted_at` column to your `$dates` property:
 
 ```php
 class User extends Model
@@ -555,6 +557,19 @@ if ($user->trashed()) {
 }
 ```
 
+If you wish, you may also change the column that the deleted timestamp is saved to, by specifying a `DELETED_AT` constant in your model. Make sure that you change the column in the `$dates` property as well.
+
+```php
+class User extends Model
+{
+    // ...
+    const DELETED_AT = 'hidden_at';
+
+    protected $dates = ['hidden_at'];
+    // ...
+}
+```
+
 ### Querying soft deleted models
 
 #### Including soft deleted models
@@ -611,21 +626,67 @@ $user->posts()->forceDelete();
 
 ### Soft deleting relations
 
-When two related models have soft deletes enabled, you can cascade the delete event by defining the `softDelete` option in the [relation definition](relations#detailed-definitions). In this example, if the user model is soft deleted, the comments belonging to that user will also be soft deleted.
+A model that uses the `SoftDelete` trait may also define that related models also be soft deleting when the primary model is soft delete. You can cascade the soft deletion by defining the `softDelete` option in the [relation definition](relations#detailed-definitions) if you are using property-style relation definitions.
+
+In this example, if the user model is soft deleted, the comments belonging to that user will also be soft deleted.
+
+```php
+class User extends Model
+{
+    use \Winter\Storm\Database\Traits\SoftDelete;
+
+    public $hasMany = [
+        'comments' => ['Acme\Blog\Models\Comment', 'softDelete' => true],
+    ];
+}
+```
+
+If your related model uses a different column for storing the deleted timestamp, you may specify it in the `deletedAtColumn` option on the relation definition.
 
 ```php
 class User extends Model
 {
     use \Winter\Storm\Database\Traits\SoftDelete;
 
     public $hasMany = [
-        'comments' => ['Acme\Blog\Models\Comment', 'softDelete' => true]
+        'comments' => [
+            'Acme\Blog\Models\Comment',
+            'softDelete' => true,
+            'deletedAtColumn' => 'hidden_at',
+        ],
     ];
 }
 ```
 
-> **NOTE:** If the soft deleting relation is using a pivot table, you can set the `deletedAtColumn` option on the relation definition to change the column that will hold the soft deletion date in the pivot table, otherwise, it defaults to `deleted_at`.
-> **NOTE:** If the related model does not use the soft delete trait, it will be treated the same as the `delete` option and deleted permanently.
+If you use method style relations, you can include the `->softDeletable()` chained method to the relation definition to indicate that this relation should also be soft deleted when the main model is soft deleted.
+
+```php
+class User extends Model
+{
+    use \Winter\Storm\Database\Traits\SoftDelete;
+
+    public function comments(): HasMany
+    {
+        $this->hasMany('Acme\Blog\Models\Comment')->softDeletable();
+    }
+}
+```
+
+If your related model uses a different column for storing the deleted timestamp, you may specify it in the first parameter of the chained method:
+
+```php
+class User extends Model
+{
+    use \Winter\Storm\Database\Traits\SoftDelete;
+
+    public function comments(): HasMany
+    {
+        $this->hasMany('Acme\Blog\Models\Comment')->softDeletable('hidden_at');
+    }
+}
+```
+
+> **WARNING:** If the related model does not also use the `SoftDelete` trait and you specify the relation as soft-deletable, the relation will be *permanently* deleted.
 
 Under these same conditions, when the primary model is restored, all the related models that use the `softDelete` option will also be restored.