improve docs

1 files changed, 27 insertions, 6 deletions

diff --git a/src/Propellor/Property/Cmd.hs b/src/Propellor/Property/Cmd.hs
index b02376a3..3db00bc1 100644
--- a/src/Propellor/Property/Cmd.hs
+++ b/src/Propellor/Property/Cmd.hs
@@ -1,7 +1,33 @@
 {-# LANGUAGE PackageImports #-}
 
+-- | This module lets you construct Properties by running commands and
+-- scripts. To get from an `UncheckedProperty` to a `Property`, it's
+-- up to the user to check if the command made a change to the system. 
+--
+-- The best approach is to `check` a property, so that the command is only
+-- run when it needs to be. With this method, you avoid running the
+-- `cmdProperty` unnecessarily, and you know that whenever it runs, a
+-- change was made.
+--
+-- > check (not <$> userExists "bob")
+-- > 	(cmdProperty "useradd" ["bob"] `assume` MadeChange)
+--
+-- Sometimes it's just as expensive to check a property as it would be to
+-- run the command that ensures the property. So you can let the command
+-- run every time, and use `changesFile` or `checkResult` to determine if
+-- anything changed:
+--
+-- > cmdProperty "chmod" ["600", "/etc/secret"]
+-- > 	`changesFile` "/etc/secret"
+--
+-- Or you can punt and `assume` a change was made, but then propellor will
+-- always say it make a change, and `onChange` will always fire.
+--
+-- > cmdProperty "service" ["foo", "reload"]
+-- > 	`assume` MadeChange
+
 module Propellor.Property.Cmd (
-	-- * Properties for running commands and scripts
+	-- * Constricting properties running commands and scripts
 	cmdProperty,
 	cmdProperty',
 	cmdPropertyEnv,
@@ -32,11 +58,6 @@ import Utility.Process (createProcess, CreateProcess, waitForProcess)
 -- | A property that can be satisfied by running a command.
 --
 -- The command must exit 0 on success.
---
--- This and other properties in this module are `UncheckedProperty`,
--- and return `NoChange`. It's up to the user to check if the command
--- made a change to the system, perhaps by using `checkResult` or
--- `changesFile`, or you can use @cmdProperty "foo" ["bar"] `assume` MadeChange@
 cmdProperty :: String -> [String] -> UncheckedProperty NoInfo
 cmdProperty cmd params = cmdProperty' cmd params id