Add note about using module_refresh to refresh modules in state run

salt/modules/saltutil.py

@@ -253,6 +253,23 @@ def sync_modules(saltenv=None, refresh=True):
     to grab the contents of the _modules directory, base is the default
     environment.
 
+    .. important::
+
+        If this function is executed using a :py:func:`module.run
+        <salt.states.module.run>` state, the SLS file will not have access to
+        newly synced execution modules unless a ``reload_modules`` argument is
+        added to the state, like so:
+
+        .. code-block:: yaml
+
+            load_my_custom_module:
+              module.run:
+                - name: saltutil.sync_modules
+                - reload_modules: True
+
+        See :ref:`here <reloading-modules>` for a more detailed explanation of
+        why this is necessary.
+
     CLI Example:
 
     .. code-block:: bash
@@ -388,6 +405,24 @@ def sync_all(saltenv=None, refresh=True):
     refresh : True
         Also refresh the execution modules available to the minion.
 
+    .. important::
+
+        If this function is executed using a :py:func:`module.run
+        <salt.states.module.run>` state, the SLS file will not have access to
+        newly synced execution modules unless a ``reload_modules`` argument is
+        added to the state, like so:
+
+        .. code-block:: yaml
+
+            load_my_custom_module:
+              module.run:
+                - name: saltutil.sync_all
+                - refresh: True
+                - reload_modules: True
+
+        See :ref:`here <reloading-modules>` for a more detailed explanation of
+        why this is necessary.
+
     CLI Example:
 
     .. code-block:: bash