Expand docs about registering markers

Author: Zac-HD

changelog/4826.feature.rst

@@ -0,0 +1,2 @@
+A warning is now emitted when unknown marks are used as a decorator.
+This is often due to a typo, which can lead to silently broken tests.

doc/en/mark.rst

@@ -26,14 +26,15 @@ which also serve as documentation.
     :ref:`fixtures <fixtures>`.
 
 
-Raising errors on unknown marks: --strict
------------------------------------------
+.. _unknown-marks:
 
-When the ``--strict`` command-line flag is passed, any unknown marks applied
-with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
-Marks defined or added by pytest or by a plugin will not trigger an error.
+Raising errors on unknown marks
+-------------------------------
 
-Marks can be registered in ``pytest.ini`` like this:
+Unknown marks applied with the ``@pytest.mark.name_of_the_mark`` decorator
+will always emit a warning, in order to avoid silently doing something
+surprising due to mis-typed names.  You can disable the warning for custom
+marks by registering them in ``pytest.ini`` like this:
 
 .. code-block:: ini
 
@@ -42,8 +43,11 @@ Marks can be registered in ``pytest.ini`` like this:
         slow
         serial
 
-This can be used to prevent users mistyping mark names by accident. Test suites that want to enforce this
-should add ``--strict`` to ``addopts``:
+When the ``--strict`` command-line flag is passed, any unknown marks applied
+with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
+Marks added by pytest or by a plugin instead of the decorator will not trigger
+the warning or this error.  Test suites that want to enforce a limited set of
+markers can add ``--strict`` to ``addopts``:
 
 .. code-block:: ini
 
@@ -53,6 +57,9 @@ should add ``--strict`` to ``addopts``:
         slow
         serial
 
+Third-party plugins should always :ref:`register their markers <registering-markers>`
+so that they appear in pytest's help text and do not emit warnings.
+
 
 .. _marker-revamp:
 

doc/en/writing_plugins.rst

@@ -286,6 +286,30 @@ the plugin manager like this:
 If you want to look at the names of existing plugins, use
 the ``--trace-config`` option.
 
+
+.. _registering-markers:
+
+Registering custom markers
+--------------------------
+
+If your plugin uses any markers, you should register them so that they appear in
+pytest's help text and do not :ref:`cause spurious warnings <unknown-marks>`.
+For example, the following plugin would register ``cool_marker`` and
+``mark_with`` for all users:
+
+.. code-block:: python
+
+    def pytest_configure(config):
+        config.addinivalue_line(
+            "markers",
+            "cool_marker: this one is for cool tests.",
+        )
+        config.addinivalue_line(
+            "markers",
+            "mark_with(arg, arg2): this marker takes arguments.",
+        )
+
+
 Testing plugins
 ---------------