Improve SoftDeletable trait docblocks

Closes #2110

# Conflicts:
#	lib/Gedmo/SoftDeleteable/Traits/SoftDeleteable.php
#	lib/Gedmo/SoftDeleteable/Traits/SoftDeleteableDocument.php
#	lib/Gedmo/SoftDeleteable/Traits/SoftDeleteableEntity.php

Author: AkenRoberts

lib/Gedmo/SoftDeleteable/Traits/SoftDeleteable.php

@@ -2,45 +2,47 @@
 
 namespace Gedmo\SoftDeleteable\Traits;
 
+use DateTime;
+
 /**
- * SoftDeletable Trait, usable with PHP >= 5.4
+ * A generic trait to use on your self-deletable entities.
+ * There is no mapping information defined in this trait.
  *
  * @author Wesley van Opdorp <[email protected]>
  * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 trait SoftDeleteable
 {
     /**
-     * @var \DateTime
+     * @var DateTime|null
      */
     protected $deletedAt;
 
     /**
-     * Sets deletedAt.
-     *
-     * @param \DateTime|null $deletedAt
+     * Set or clear the deleted at timestamp.
      *
-     * @return $this
+     * @return self
      */
-    public function setDeletedAt(\DateTime $deletedAt = null)
+    public function setDeletedAt(DateTime $deletedAt = null)
     {
         $this->deletedAt = $deletedAt;
 
         return $this;
     }
 
     /**
-     * Returns deletedAt.
+     * Get the deleted at timestamp value. Will return null if
+     * the entity has not been soft deleted.
      *
-     * @return \DateTime
+     * @return DateTime|null
      */
     public function getDeletedAt()
     {
         return $this->deletedAt;
     }
 
     /**
-     * Is deleted?
+     * Check if the entity has been soft deleted.
      *
      * @return bool
      */

lib/Gedmo/SoftDeleteable/Traits/SoftDeleteableDocument.php

@@ -2,48 +2,50 @@
 
 namespace Gedmo\SoftDeleteable\Traits;
 
+use DateTime;
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
 
 /**
- * SoftDeletable Trait, usable with PHP >= 5.4
+ * A soft deletable trait you can apply to your MongoDB entities.
+ * Includes default annotation mapping.
  *
  * @author Wesley van Opdorp <[email protected]>
  * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 trait SoftDeleteableDocument
 {
     /**
-     * @var \DateTime
      * @ODM\Field(type="date")
+     *
+     * @var DateTime|null
      */
     protected $deletedAt;
 
     /**
-     * Sets deletedAt.
-     *
-     * @param \DateTime|null $deletedAt
+     * Set or clear the deleted at timestamp.
      *
-     * @return $this
+     * @return self
      */
-    public function setDeletedAt(\DateTime $deletedAt = null)
+    public function setDeletedAt(DateTime $deletedAt = null)
     {
         $this->deletedAt = $deletedAt;
 
         return $this;
     }
 
     /**
-     * Returns deletedAt.
+     * Get the deleted at timestamp value. Will return null if
+     * the entity has not been soft deleted.
      *
-     * @return \DateTime
+     * @return DateTime|null
      */
     public function getDeletedAt()
     {
         return $this->deletedAt;
     }
 
     /**
-     * Is deleted?
+     * Check if the entity has been soft deleted.
      *
      * @return bool
      */

lib/Gedmo/SoftDeleteable/Traits/SoftDeleteableEntity.php

@@ -2,48 +2,50 @@
 
 namespace Gedmo\SoftDeleteable\Traits;
 
+use DateTime;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
- * SoftDeletable Trait, usable with PHP >= 5.4
+ * A soft deletable trait you can apply to your Doctrine ORM entities.
+ * Includes default annotation mapping.
  *
  * @author Wesley van Opdorp <[email protected]>
  * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 trait SoftDeleteableEntity
 {
     /**
-     * @var \DateTime
      * @ORM\Column(type="datetime", nullable=true)
+     *
+     * @var DateTime|null
      */
     protected $deletedAt;
 
     /**
-     * Sets deletedAt.
-     *
-     * @param \DateTime|null $deletedAt
+     * Set or clear the deleted at timestamp.
      *
-     * @return $this
+     * @return self
      */
-    public function setDeletedAt(\DateTime $deletedAt = null)
+    public function setDeletedAt(DateTime $deletedAt = null)
     {
         $this->deletedAt = $deletedAt;
 
         return $this;
     }
 
     /**
-     * Returns deletedAt.
+     * Get the deleted at timestamp value. Will return null if
+     * the entity has not been soft deleted.
      *
-     * @return \DateTime
+     * @return DateTime|null
      */
     public function getDeletedAt()
     {
         return $this->deletedAt;
     }
 
     /**
-     * Is deleted?
+     * Check if the entity has been soft deleted.
      *
      * @return bool
      */