Add a warning about usefixtures mark not working in fixtures

Fix #1014

Author: nicoddemus

doc/en/fixture.rst

@@ -943,7 +943,7 @@ a generic feature of the mark mechanism:
 Note that the assigned variable *must* be called ``pytestmark``, assigning e.g.
 ``foomark`` will not activate the fixtures.
 
-Lastly you can put fixtures required by all tests in your project
+It is also possible to put fixtures required by all tests in your project
 into an ini-file:
 
 .. code-block:: ini
@@ -953,6 +953,22 @@ into an ini-file:
     usefixtures = cleandir
 
 
+.. warning::
+
+    Note this mark has no effect in **fixture functions**. For example,
+    this **will not work as expected**:
+
+    .. code-block:: python
+
+        @pytest.mark.usefixtures("my_other_fixture")
+        @pytest.fixture
+        def my_fixture_that_sadly_wont_use_my_other_fixture():
+            ...
+
+    Currently this will not generate any error or warning, but this is intended
+    to be handled by `#3664 <https://github.com/pytest-dev/pytest/issues/3664>`_.
+
+
 .. _`autouse`:
 .. _`autouse fixtures`:
 

doc/en/reference.rst

@@ -170,9 +170,14 @@ pytest.mark.usefixtures
 
 Mark a test function as using the given fixture names.
 
+.. warning::
+
+    This mark can be used with *test functions* only, having no affect when applied
+    to a **fixture** function.
+
 .. py:function:: pytest.mark.usefixtures(*names)
 
-    :param args: the names of the fixture to use as strings
+    :param args: the names of the fixture to use, as strings
 
 
 .. _`pytest.mark.xfail ref`: