Update mod_watch() description for all states.

salt/states/at.py

@@ -292,6 +292,12 @@ def mod_watch(name, **kwargs):
     '''
     The at watcher, called to invoke the watch command.
 
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
+
     name
         The name of the atjob
 

salt/states/cmd.py

@@ -1233,6 +1233,12 @@ def wait_call(name,
 def mod_watch(name, **kwargs):
     '''
     Execute a cmd function based on a watch call
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
     '''
     if kwargs['sfun'] in ('wait', 'run', 'watch'):
         if kwargs.get('stateful'):

salt/states/docker_container.py

@@ -2049,6 +2049,15 @@ def absent(name, force=False):
 
 
 def mod_watch(name, sfun=None, **kwargs):
+    '''
+    The docker_container watcher, called to invoke the watch command.
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
+    '''
     if sfun == 'running':
         watch_kwargs = copy.deepcopy(kwargs)
         if watch_kwargs.get('watch_action', 'force') == 'force':

salt/states/docker_image.py

@@ -411,6 +411,15 @@ def absent(name=None, images=None, force=False):
 
 
 def mod_watch(name, sfun=None, **kwargs):
+    '''
+    The docker_image  watcher, called to invoke the watch command.
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
+    '''
     if sfun == 'present':
         # Force image to be updated
         kwargs['force'] = True

salt/states/etcd_mod.py

@@ -253,7 +253,14 @@ def wait_rm(name, recurse=False, profile=None):
 
 def mod_watch(name, **kwargs):
     '''
-    Execute a etcd function based on a watch call requisite.
+    The etcd watcher, called to invoke the watch command.
+    When called, execute a etcd function based on a watch call requisite.
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
     '''
 
     # Watch to set etcd key

salt/states/mount.py

@@ -808,6 +808,12 @@ def mod_watch(name, user=None, **kwargs):
     '''
     The mounted watcher, called to invoke the watch command.
 
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
+
     name
         The name of the mount point
 

salt/states/pkg.py

@@ -3186,6 +3186,12 @@ def mod_aggregate(low, chunks, running):
 def mod_watch(name, **kwargs):
     '''
     Install/reinstall a package based on a watch requisite
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
     '''
     sfun = kwargs.pop('sfun', None)
     mapfun = {'purged': purged,

salt/states/supervisord.py

@@ -361,7 +361,16 @@ def mod_watch(name,
               conf_file=None,
               bin_env=None,
               **kwargs):
-    # Always restart on watch
+    '''
+    The supervisord watcher, called to invoke the watch command.
+    Always restart on watch
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
+    '''
     return running(
         name,
         restart=restart,

salt/states/tomcat.py

@@ -270,8 +270,14 @@ def wait(name, url='http://localhost:8080/manager', timeout=180):
 
 def mod_watch(name, url='http://localhost:8080/manager', timeout=180):
     '''
-    The tomcat watcher function.
-    When called it will reload the webapp in question
+    The tomcat watcher, called to invoke the watch command.
+    When called, it will reload the webapp in question
+
+    .. note::
+        This state exists to support special handling of the ``watch``
+        :ref:`requisite <requisites>`. It should not be called directly.
+
+        Parameters for this function should be set by the state being triggered.
     '''
 
     msg = __salt__['tomcat.reload'](name, url, timeout)