From fa466519c4bdb6baea07e6b9f34b33a1ae4953f1 Mon Sep 17 00:00:00 2001
From: rallytime <nicole@saltstack.com>
Date: Mon, 24 Jul 2017 13:22:50 -0600
Subject: [PATCH 1/2] Add a mention of the True/False returns with
 __virtual__()

And their relationship to `__virtualname__`.

Fixes #42375
---
 doc/ref/modules/index.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/ref/modules/index.rst b/doc/ref/modules/index.rst
index 9f81170fe4..1056ba40f8 100644
--- a/doc/ref/modules/index.rst
+++ b/doc/ref/modules/index.rst
@@ -405,6 +405,10 @@ similar to the following:
            return __virtualname__
        return False
 
+Note that the ``__virtual__()`` function will return either a ``True`` or ``False``
+value. If it returns a ``True`` value, this ``__virtualname__`` module-level attribute
+can be set as seen in the above example. This is the name that the module should be
+referred to as.
 
 Documentation
 =============

From 685c2cced680ffb5745b3eaa8754ff9eb887fe50 Mon Sep 17 00:00:00 2001
From: rallytime <nicole@saltstack.com>
Date: Tue, 25 Jul 2017 14:44:18 -0600
Subject: [PATCH 2/2] Add information about returning a tuple with an error
 message

---
 doc/ref/modules/index.rst | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/doc/ref/modules/index.rst b/doc/ref/modules/index.rst
index 1056ba40f8..3bd62b3c41 100644
--- a/doc/ref/modules/index.rst
+++ b/doc/ref/modules/index.rst
@@ -405,10 +405,29 @@ similar to the following:
            return __virtualname__
        return False
 
-Note that the ``__virtual__()`` function will return either a ``True`` or ``False``
-value. If it returns a ``True`` value, this ``__virtualname__`` module-level attribute
-can be set as seen in the above example. This is the name that the module should be
-referred to as.
+The ``__virtual__()`` function can return a ``True`` or ``False`` boolean, a tuple,
+or a string. If it returns a ``True`` value, this ``__virtualname__`` module-level
+attribute can be set as seen in the above example. This is the string that the module
+should be referred to as.
+
+When ``__virtual__()`` returns a tuple, the first item should be a boolean and the
+second should be a string. This is typically done when the module should not load. The
+first value of the tuple is ``False`` and the second is the error message to display
+for why the module did not load.
+
+For example:
+
+.. code-block:: python
+
+    def __virtual__():
+        '''
+        Only load if git exists on the system
+        '''
+        if salt.utils.which('git') is None:
+            return (False,
+                    'The git execution module cannot be loaded: git unavailable.')
+        else:
+            return True
 
 Documentation
 =============