diff --git a/docs/api/index.rst b/docs/api/index.rst
index 557cac3..fde1ac6 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -80,6 +80,9 @@ api.env
 .. autosummary::
 
     api.env.adopt_roles
+    api.env.adopt_user
+    api.env.debug_mode
+    api.env.test_mode
 
 
 Exceptions and errors
diff --git a/docs/env.rst b/docs/env.rst
index a677716..98e6199 100644
--- a/docs/env.rst
+++ b/docs/env.rst
@@ -70,6 +70,8 @@ To temporarily override the user which is currently active, use
         "doc_owner",
     )
 
+.. _env_debug_mode_example:
+
 Debug mode
 ----------
 
@@ -84,6 +86,9 @@ To know if your zope instance is running in debug mode, use
     if in_debug_mode:
         print 'Zope is in debug mode'
 
+
+.. _env_test_mode_example:
+
 Test mode
 ---------
 
diff --git a/src/plone/api/env.py b/src/plone/api/env.py
index 6b77ae6..5f73f0c 100644
--- a/src/plone/api/env.py
+++ b/src/plone/api/env.py
@@ -163,12 +163,18 @@ class _GlobalRoleOverridingContext(object):
 
 
 def debug_mode():
-    """Returns True if your zope instance is running in debug mode."""
+    """Returns True if your zope instance is running in debug mode.
+
+    :Example: :ref:`env_debug_mode_example`
+    """
     return Globals.DevelopmentMode
 
 
 def test_mode():
-    """Returns True if you are running the zope test runner."""
+    """Returns True if you are running the zope test runner.
+
+    :Example: :ref:`env_test_mode_example`
+    """
     from plone.api import env
 
     if env.IS_TEST is None: