[1.8.x] Fixed #25174 -- Moved some details of CheckMessage to the reference guide.

Backport of faa2a0f662ed6fe0b90d10e98cc8ee3795d9307c from master

1 files changed, 36 insertions, 60 deletions

diff --git a/docs/topics/checks.txt b/docs/topics/checks.txt
index b840c4b942..9be7c65805 100644
--- a/docs/topics/checks.txt
+++ b/docs/topics/checks.txt
@@ -31,12 +31,21 @@ The framework is flexible and allows you to write functions that perform
 any other kind of check you may require. The following is an example stub
 check function::
 
-    from django.core.checks import register
+    from django.core.checks import Error, register
 
     @register()
     def example_check(app_configs, **kwargs):
         errors = []
         # ... your check logic here
+        if check_failed:
+            errors.append(
+                Error(
+                    'an error',
+                    hint=None,
+                    obj=checked_object,
+                    id='myapp.E001',
+                )
+            )
         return errors
 
 The check function *must* accept an ``app_configs`` argument; this argument is
@@ -50,75 +59,25 @@ Messages
 The function must return a list of messages. If no problems are found as a result
 of the check, the check function must return an empty list.
 
-.. class:: CheckMessage(level, msg, hint, obj=None, id=None)
-
 The warnings and errors raised by the check method must be instances of
 :class:`~django.core.checks.CheckMessage`. An instance of
 :class:`~django.core.checks.CheckMessage` encapsulates a single reportable
 error or warning. It also provides context and hints applicable to the
 message, and a unique identifier that is used for filtering purposes.
 
-The concept is very similar to messages from the :doc:`message
-framework </ref/contrib/messages>` or the :doc:`logging framework
-</topics/logging>`. Messages are tagged with a ``level`` indicating the
-severity of the message.
-
-Constructor arguments are:
-
-``level``
-    The severity of the message. Use one of the
-    predefined values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
-    ``CRITICAL``. If the level is greater or equal to ``ERROR``, then Django
-    will prevent management commands from executing. Messages with
-    level lower than ``ERROR`` (i.e. warnings) are reported to the console,
-    but can be silenced.
-
-``msg``
-    A short (less than 80 characters) string describing the problem. The string
-    should *not* contain newlines.
-
-``hint``
-    A single-line string providing a hint for fixing the problem. If no hint
-    can be provided, or the hint is self-evident from the error message, the
-    hint can be omitted, or a value of ``None`` can be used.
-
-``obj``
-    Optional. An object providing context for the message (for example, the
-    model where the problem was discovered). The object should be a model, field,
-    or manager or any other object that defines ``__str__`` method (on
-    Python 2 you need to define ``__unicode__`` method). The method is used while
-    reporting all messages and its result precedes the message.
-
-``id``
-    Optional string. A unique identifier for the issue. Identifiers should
-    follow the pattern ``applabel.X001``, where ``X`` is one of the letters
-    ``CEWID``, indicating the message severity (``C`` for criticals,
-    ``E`` for errors and so). The number can be allocated by the application,
-    but should be unique within that application.
+The concept is very similar to messages from the :doc:`message framework
+</ref/contrib/messages>` or the :doc:`logging framework </topics/logging>`.
+Messages are tagged with a ``level`` indicating the severity of the message.
 
 There are also shortcuts to make creating messages with common levels easier.
-When using these methods you can omit the ``level`` argument because it is
+When using these classes you can omit the ``level`` argument because it is
 implied by the class name.
 
-.. class:: Debug(msg, hint, obj=None, id=None)
-.. class:: Info(msg, hint, obj=None, id=None)
-.. class:: Warning(msg, hint, obj=None, id=None)
-.. class:: Error(msg, hint, obj=None, id=None)
-.. class:: Critical(msg, hint, obj=None, id=None)
-
-Messages are comparable. That allows you to easily write tests::
-
-    from django.core.checks import Error
-    errors = checked_object.check()
-    expected_errors = [
-        Error(
-            'an error',
-            hint=None,
-            obj=checked_object,
-            id='myapp.E001',
-        )
-    ]
-    self.assertEqual(errors, expected_errors)
+* :class:`Debug`
+* :class:`Info`
+* :class:`Warning`
+* :class:`Error`
+* :class:`Critical`
 
 Registering and labeling checks
 -------------------------------
@@ -234,3 +193,20 @@ the only difference is that the check is a classmethod, not an instance method::
             errors = super(MyModel, cls).check(**kwargs)
             # ... your own checks ...
             return errors
+
+Writing Tests
+-------------
+
+Messages are comparable. That allows you to easily write tests::
+
+    from django.core.checks import Error
+    errors = checked_object.check()
+    expected_errors = [
+        Error(
+            'an error',
+            hint=None,
+            obj=checked_object,
+            id='myapp.E001',
+        )
+    ]
+    self.assertEqual(errors, expected_errors)