diff --git a/_pytest/recwarn.py b/_pytest/recwarn.py
index 4fceb10a7..ab0f79c75 100644
--- a/_pytest/recwarn.py
+++ b/_pytest/recwarn.py
@@ -16,10 +16,7 @@ from _pytest.outcomes import fail
 
 @yield_fixture
 def recwarn():
-    """Return a WarningsRecorder instance that provides these methods:
-
-    * ``pop(category=None)``: return last warning matching the category.
-    * ``clear()``: clear list of warnings
+    """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
     See http://docs.python.org/library/warnings.html for information
     on warning categories.
@@ -88,11 +85,11 @@ class _DeprecatedCallContext(object):
 def warns(expected_warning, *args, **kwargs):
     """Assert that code raises a particular class of warning.
 
-    Specifically, the input @expected_warning can be a warning class or
-    tuple of warning classes, and the code must return that warning
-    (if a single class) or one of those warnings (if a tuple).
+    Specifically, the parameter ``expected_warning`` can be a warning class or
+    sequence of warning classes, and the inside the ``with`` block must issue a warning of that class or
+    classes.
 
-    This helper produces a list of ``warnings.WarningMessage`` objects,
+    This helper produces a list of :class:`warnings.WarningMessage` objects,
     one for each warning raised.
 
     This function can be used as a context manager, or any of the other ways
diff --git a/_pytest/tmpdir.py b/_pytest/tmpdir.py
index 66b4a2d2f..315ead302 100644
--- a/_pytest/tmpdir.py
+++ b/_pytest/tmpdir.py
@@ -116,6 +116,8 @@ def tmpdir(request, tmpdir_factory):
     created as a sub directory of the base temporary
     directory.  The returned object is a `py.path.local`_
     path object.
+
+    .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
     """
     name = request.node.name
     name = re.sub(r"[\W]", "_", name)
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 77a8ba11a..a06e37007 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -9,8 +9,8 @@ This page contains the full reference to pytest's API.
     :local:
 
 
-approx
-------
+pytest.approx
+-------------
 
 .. autofunction:: _pytest.python_api.approx
 
@@ -67,6 +67,15 @@ pytest.deprecated_call
 .. autofunction:: _pytest.recwarn.deprecated_call
     :with:
 
+pytest.warns
+------------
+
+**Tutorial**: :ref:`assertwarnings`
+
+.. autofunction:: _pytest.recwarn.warns
+    :with:
+
+
 .. _`hook-reference`:
 
 Hooks
@@ -250,6 +259,10 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 .. autoclass:: pluggy.PluginManager()
     :members:
 
+.. autoclass:: pluggy.PluginManager()
+    :members:
+
+
 
 Fixtures
 --------
@@ -485,3 +498,52 @@ To use it, include in your top-most ``conftest.py`` file::
 
 .. autoclass:: LineMatcher()
     :members:
+
+
+recwarn
+~~~~~~~
+
+**Tutorial**: :ref:`assertwarnings`
+
+.. currentmodule:: _pytest.recwarn
+
+.. autofunction:: recwarn()
+    :no-auto-options:
+
+.. autoclass:: _pytest.recwarn.WarningsRecorder()
+    :members:
+
+Each recorded warning is an instance of :class:`warnings.WarningMessage`.
+
+.. note::
+    :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1
+
+.. note::
+    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
+    differently; see :ref:`ensuring_function_triggers`.
+
+
+tmpdir
+~~~~~~
+
+**Tutorial**: :doc:`tmpdir`
+
+.. currentmodule:: _pytest.tmpdir
+
+.. autofunction:: tmpdir()
+    :no-auto-options:
+
+
+tmpdir_factory
+~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`tmpdir factory example`
+
+.. _`tmpdir factory api`:
+
+``tmpdir_factory`` instances have the following methods:
+
+.. currentmodule:: _pytest.tmpdir
+
+.. automethod:: TempdirFactory.mktemp
+.. automethod:: TempdirFactory.getbasetemp
diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst
index b9c371e40..e01d359e0 100644
--- a/doc/en/tmpdir.rst
+++ b/doc/en/tmpdir.rst
@@ -51,6 +51,9 @@ Running this would result in a passed test except for the last
     test_tmpdir.py:7: AssertionError
     ========================= 1 failed in 0.12 seconds =========================
 
+
+.. _`tmpdir factory example`:
+
 The 'tmpdir_factory' fixture
 ----------------------------
 
@@ -81,12 +84,8 @@ to save time:
         img = load_image(image_file)
         # compute and test histogram
 
-``tmpdir_factory`` instances have the following methods:
+See :ref:`tmpdir_factory API <tmpdir factory api>` for details.
 
-.. currentmodule:: _pytest.tmpdir
-
-.. automethod:: TempdirFactory.mktemp
-.. automethod:: TempdirFactory.getbasetemp
 
 .. _`base temporary directory`:
 
diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index d5a627aea..df61e1f38 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -250,23 +250,11 @@ The ``recwarn`` fixture will record warnings for the whole function::
 Both ``recwarn`` and ``pytest.warns`` return the same interface for recorded
 warnings: a WarningsRecorder instance. To view the recorded warnings, you can
 iterate over this instance, call ``len`` on it to get the number of recorded
-warnings, or index into it to get a particular recorded warning. It also
-provides these methods:
+warnings, or index into it to get a particular recorded warning.
 
-.. autoclass:: _pytest.recwarn.WarningsRecorder()
-    :members:
+.. currentmodule:: _pytest.warnings
 
-Each recorded warning has the attributes ``message``, ``category``,
-``filename``, ``lineno``, ``file``, and ``line``. The ``category`` is the
-class of the warning. The ``message`` is the warning itself; calling
-``str(message)`` will return the actual message of the warning.
-
-.. note::
-    :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1
-
-.. note::
-    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
-    differently; see :ref:`ensuring_function_triggers`.
+Full API: :class:`WarningsRecorder`.
 
 .. _`ensuring a function triggers a deprecation warning`: