From fb6ec3ad0072c60eb62e0a17c9c87e439e721fbc Mon Sep 17 00:00:00 2001
From: Sage Abdullah <sage.abdullah@torchbox.com>
Date: Mon, 15 Aug 2022 14:02:24 +0700
Subject: [PATCH] Add docs for DraftStateMixin

---
 docs/reference/pages/model_reference.md | 60 +++++++++++++++++++++++++
 wagtail/models/__init__.py              | 34 ++++++++------
 2 files changed, 81 insertions(+), 13 deletions(-)

diff --git a/docs/reference/pages/model_reference.md b/docs/reference/pages/model_reference.md
index 99875b838e..463e3ec288 100644
--- a/docs/reference/pages/model_reference.md
+++ b/docs/reference/pages/model_reference.md
@@ -523,6 +523,66 @@ The model is added to allow Snippets to save revisions, revert to a previous rev
     .. automethod:: with_content_json
 ```
 
+## `DraftStateMixin`
+
+`DraftStateMixin` is an abstract model that can be added to any non-page Django model to allow its instances to have unpublished changes.
+This mixin requires {class}`~wagtail.models.RevisionMixin` to be applied. Pages already include this mixin, so there is no need to add it.
+
+```{versionadded} 4.0
+The model is added to allow Snippets to have changes that are not immediately reflected to the instance.
+```
+
+### Database fields
+
+```{eval-rst}
+.. class:: DraftStateMixin
+
+    .. attribute:: live
+
+        (boolean)
+
+        A boolean that is set to ``True`` if the object is published.
+
+        Note: this field defaults to ``True`` meaning that any objects that are created programmatically will be published by default.
+
+    .. attribute:: live_revision
+
+        (foreign key to :class:`~wagtail.models.Revision`)
+
+        This points to the revision that is currently live.
+
+    .. attribute:: has_unpublished_changes
+
+        (boolean)
+
+        A boolean that is set to ``True`` when the object is either in draft or published with draft changes.
+
+    .. attribute:: first_published_at
+
+        (date/time)
+
+        The date/time when the object was first published.
+
+    .. attribute:: last_published_at
+
+        (date/time)
+
+        The date/time when the object was last published.
+```
+
+### Methods and properties
+
+```{eval-rst}
+.. class:: DraftStateMixin
+    :noindex:
+
+    .. automethod:: publish
+
+    .. automethod:: unpublish
+
+    .. automethod:: with_content_json
+```
+
 (revision_model_ref)=
 
 ## `Revision`
diff --git a/wagtail/models/__init__.py b/wagtail/models/__init__.py
index 006c836c1d..95ab9f60f2 100644
--- a/wagtail/models/__init__.py
+++ b/wagtail/models/__init__.py
@@ -480,6 +480,17 @@ class DraftStateMixin(models.Model):
     def publish(
         self, revision, user=None, changed=True, log_action=True, previous_revision=None
     ):
+        """
+        Publish a revision of the object by applying the changes in the revision to the live object.
+
+        :param revision: Revision to publish.
+        :type revision: Revision
+        :param user: The publishing user.
+        :param changed: Indicated whether content has changed.
+        :param log_action: Flag for the logging action, pass ``False`` to skip logging.
+        :param previous_revision: Indicates a revision reversal. Should be set to the previous revision instance.
+        :type previous_revision: Revision
+        """
         return PublishRevisionAction(
             revision,
             user=user,
@@ -489,6 +500,14 @@ class DraftStateMixin(models.Model):
         ).execute()
 
     def unpublish(self, set_expired=False, commit=True, user=None, log_action=True):
+        """
+        Unpublish the live object.
+
+        :param set_expired: Mark the object as expired.
+        :param commit: Commit the changes to the database.
+        :param user: The unpublishing user.
+        :param log_action: Flag for the logging action, pass ``False`` to skip logging.
+        """
         return UnpublishAction(
             self,
             set_expired=set_expired,
@@ -499,23 +518,12 @@ class DraftStateMixin(models.Model):
 
     def with_content_json(self, content):
         """
-        Returns a new version of the object with field values updated to reflect changes
-        in the provided ``content`` (which usually comes from a previously-saved revision).
+        Similar to :meth:`RevisionMixin.with_content_json`,
+        but with the following fields also preserved:
 
-        Certain field values are preserved in order to prevent errors if the returned
-        object is saved, such as ``id``. The following field values are also preserved,
-        as they are considered to be meaningful to the object as a whole, rather than
-        to a specific revision:
-
-        * ``latest_revision``
         * ``live``
         * ``has_unpublished_changes``
         * ``first_published_at``
-
-        If ``TranslatableMixin`` is applied, the following field values are also preserved:
-
-        * ``translation_key``
-        * ``locale``
         """
         obj = super().with_content_json(content)