Improve documentation of check_cmd.

* Make the distinction between requisite `check_cmd` and `file.managed`
  `check_cmd`.

* Be more clear about `file.managed` `check_cmd`, the temporary file,
  and when the new contents are written or discarded.

* In requisite `check_cmd` use a concise `!` rather than the awkward
  `&& exit 1 || exit 0`.

* A few minor, stylistic changes.

doc/man/salt.7

@@ -163290,7 +163290,7 @@ The state altering system is used to make sure that states are evaluated exactly
 as the user expects. It can be used to double check that a state preformed
 exactly how it was expected to, or to make 100% sure that a state only runs
 under certain conditions. The use of unless or onlyif options help make states
-even more stateful. The check_cmds option helps ensure that the result of a
+even more stateful. The \fBcheck_cmd\fP option helps ensure that the result of a
 state is evaluated correctly.
 .SS Unless
 .sp
@@ -163468,19 +163468,27 @@ comment\-repo:
     \- pattern: ^enabled=0
     \- repl: enabled=1
     \- check_cmd:
-      \- grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo && exit 1 || exit 0
+      \- ! grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
 This will attempt to do a replace on all enabled=0 in the .repo file, and
-replace them with enabled=1. The check_cmd is just a bash command. It will do
-a grep for enabled=0 in the file, and if it finds any, it will return a 0, which
-will prompt the && portion of the command to return a 1, causing check_cmd to
-set the state as failed. If it returns a 1, meaning it didn\(aqt find any
-\(aqenabled=0\(aq it will hit the || portion of the command, returning a 0, and
-declaring the function succeeded.
+replace them with enabled=1. The \fBcheck_cmd\fP is just a bash command. It
+will do a grep for enabled=0 in the file, and if it finds any, it will return
+a 0, which will be inverted by the leading \(aq!\(aq, causing \fBcheck_cmd\fP
+to set the state as failed. If it returns a 1, meaning it didn\(aqt find any
+\(aqenabled=0\(aq, it will be inverted by the leading \(aq!\(aq, returning a
+0, and declaring the function succeeded.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This requisite \fBcheck_cmd\fP functions differently than the \fBcheck_cmd\fP
+of the \fBfile.managed\fP state.
+.UNINDENT
+.UNINDENT
 .SS Overriding Checks
 .sp
 There are two commands used for the above checks.
@@ -163489,7 +163497,7 @@ There are two commands used for the above checks.
 override the global check for these to variables, include a \fBmod_run_check\fP in the
 salt/states/ file.
 .sp
-\fBmod_run_check_cmd\fP is used to check for the check_cmd options. To override
+\fBmod_run_check_cmd\fP is used to check for the \fBcheck_cmd\fP options. To override
 this one, include a \fBmod_run_check_cmd\fP in the states file for the state.
 .SS Startup States
 .sp
@@ -176312,9 +176320,19 @@ file to which the symlink points.
 New in version 2014.7.0.
 
 .sp
-The specified command will be run with the managed file as an argument.
-If the command exits with a nonzero exit code, the command will not be
-run.
+The specified command will be run with an appended argument of a
+.I temporary
+file containing the new managed contents.  If the command exits with a zero
+status the new managed contents will be written to the managed destination.
+If the command exits with a nonzero exit code, the new managed contents will
+be discarded.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This \fBcheck_cmd\fP functions differently than the requisite \fBcheck_cmd\fP.
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .UNINDENT
 .INDENT 0.0

doc/ref/states/requisites.rst

@@ -452,7 +452,7 @@ The state altering system is used to make sure that states are evaluated exactly
 as the user expects. It can be used to double check that a state preformed
 exactly how it was expected to, or to make 100% sure that a state only runs
 under certain conditions. The use of unless or onlyif options help make states
-even more stateful. The check_cmds option helps ensure that the result of a
+even more stateful. The ``check_cmd`` option helps ensure that the result of a
 state is evaluated correctly.
 
 Unless
@@ -602,16 +602,19 @@ same privileges as the salt-minion.
         - pattern: ^enabled=0
         - repl: enabled=1
         - check_cmd:
-          - grep 'enabled=0' /etc/yum.repos.d/fedora.repo && exit 1 || exit 0
+          - ! grep 'enabled=0' /etc/yum.repos.d/fedora.repo
 
-This will attempt to do a replace on all enabled=0 in the .repo file, and
-replace them with enabled=1. The check_cmd is just a bash command. It will do
-a grep for enabled=0 in the file, and if it finds any, it will return a 0, which
-will prompt the && portion of the command to return a 1, causing check_cmd to
-set the state as failed. If it returns a 1, meaning it didn't find any
-'enabled=0' it will hit the || portion of the command, returning a 0, and
+This will attempt to do a replace on all ``enabled=0`` in the .repo file, and
+replace them with ``enabled=1``. The ``check_cmd`` is just a bash command. It
+will do a grep for ``enabled=0`` in the file, and if it finds any, it will
+return a 0, which will be inverted by the leading ``!``, causing ``check_cmd``
+to set the state as failed. If it returns a 1, meaning it didn't find any
+``enabled=0``, it will be inverted by the leading ``!``, returning a 0, and
 declaring the function succeeded.
 
+**NOTE**: This requisite ``check_cmd`` functions differently than the ``check_cmd``
+of the ``file.managed`` state.
+
 Overriding Checks
 -----------------
 

salt/states/file.py

@@ -1328,9 +1328,14 @@ def managed(name,
     check_cmd
         .. versionadded:: 2014.7.0
 
-        The specified command will be run with the managed file as an argument.
-        If the command exits with a nonzero exit code, the command will not be
-        run.
+        The specified command will be run with an appended argument of a *temporary*
+        file containing the new managed contents.  If the command exits with a zero
+        status the new managed contents will be written to the managed destination.
+        If the command exits with a nonzero exit code, the new managed contents will
+        be discarded.
+
+        **NOTE**: This ``check_cmd`` functions differently than the requisite
+        ``check_cmd``.
     '''
     name = os.path.expanduser(name)