Clean up documentation/language in service state. (Fixes #40819)

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

@@ -1311,6 +1311,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

@@ -2614,6 +2614,15 @@ def mod_run_check(onlyif, unless, creates):
 
 
 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

@@ -503,6 +503,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

@@ -334,7 +334,14 @@ def wait_rm(name, recurse=False, profile=None, **kwargs):
 
 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/kernelpkg.py

@@ -203,7 +203,14 @@ def latest_wait(name, at_time=None, **kwargs):  # pylint: disable=unused-argumen
 
 def mod_watch(name, sfun, **kwargs):
     '''
-    Execute a kernelpkg state based on a watch or listen call
+    The kernerpkg watcher, called to invoke the watch command.
+    When called, execute a kernelpkg state based on a watch or listen 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 sfun in ('latest_active', 'latest_wait'):
         return latest_active(name, **kwargs)

salt/states/mount.py

@@ -931,6 +931,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

@@ -3264,6 +3264,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/service.py

@@ -3,10 +3,10 @@
 Starting or restarting of services and daemons
 ==============================================
 
-Services are defined as system daemons typically started with system init or
-rc scripts. The service state uses whichever service module that is loaded on
-the minion with the virtualname of ``service``. Services can be defined as
-running or dead.
+Services are defined as system daemons and are typically launched using system
+init or rc scripts. This service state uses whichever service module is loaded
+on the minion with the virtualname of ``service``. Services can be defined as
+either running or dead.
 
 If you need to know if your init system is supported, see the list of supported
 :mod:`service modules <salt.modules.service.py>` for your desired init system
@@ -30,7 +30,7 @@
     httpd:
       service.running: []
 
-The service can also be set to be started at runtime via the enable option:
+The service can also be set to start at runtime via the enable option:
 
 .. code-block:: yaml
 
@@ -39,8 +39,8 @@
         - enable: True
 
 By default if a service is triggered to refresh due to a watch statement the
-service is by default restarted. If the desired behavior is to reload the
-service, then set the reload value to True:
+service is restarted. If the desired behavior is to reload the service, then
+set the reload value to True:
 
 .. code-block:: yaml
 
@@ -832,6 +832,14 @@ def mod_watch(name,
               **kwargs):
     '''
     The service watcher, called to invoke the watch command.
+    When called, it will restart or reload the named service.
+
+    .. 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 watching service.
+        (i.e. ``service.running``)
 
     name
         The name of the init or rc script used to manage the service
@@ -844,11 +852,13 @@ def mod_watch(name,
         The string to search for when looking for the service process with ps
 
     reload
-        Use reload instead of the default restart (exclusive option with full_restart,
-        defaults to reload if both are used)
+        When set, reload the service instead of restarting it.
+        (i.e. ``service nginx reload``)
 
     full_restart
-        Use service.full_restart instead of restart (exclusive option with reload)
+        Perform a full stop/start of a service by passing ``--full-restart``.
+        This option is ignored if ``reload`` is set and is supported by only a few
+        :py:func:`service modules <salt.modules.service>`.
 
     force
         Use service.force_reload instead of reload (needs reload to be set to True)

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

@@ -272,8 +272,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)