diff --git a/_pytest/nodes.py b/_pytest/nodes.py
index 00f49cd8a..43e81da9b 100644
--- a/_pytest/nodes.py
+++ b/_pytest/nodes.py
@@ -204,7 +204,9 @@ class Node(object):
                     yield node, mark
 
     def get_closest_marker(self, name, default=None):
-        """return the first marker matching the name
+        """return the first marker matching the name, from closest (for example function) to farther level (for example
+        module level).
+
         :param default: fallback return value of no marker was found
         :param name: name to filter by
         """
@@ -214,9 +216,11 @@ class Node(object):
         """ get a marker object from this node or None if
         the node doesn't have a marker with that name.
 
-        ..warning::
-
-          deprecated
+        .. deprecated:: 3.6
+            This function has been deprecated in favor of
+            :meth:`Node.get_closest_marker <_pytest.nodes.Node.get_closest_marker>` and
+            :meth:`Node.iter_markers <_pytest.nodes.Node.iter_markers>`, see :ref:`update marker code`
+            for more details.
         """
         markers = list(self.iter_markers(name=name))
         if markers:
diff --git a/doc/en/mark.rst b/doc/en/mark.rst
index 97b632330..342e6f563 100644
--- a/doc/en/mark.rst
+++ b/doc/en/mark.rst
@@ -51,6 +51,9 @@ in fact, markers where only accessible in functions, even if they where declared
 
 A new API to access markers has been introduced in pytest 3.6 in order to solve the problems with the initial design, providing :func:`_pytest.nodes.Node.iter_markers` method to iterate over markers in a consistent manner and reworking the internals, which solved great deal of problems with the initial design.
 
+
+.. _update marker code:
+
 Updating code
 ~~~~~~~~~~~~~