#803, clarify the docs that Action goes in parallel

Author: ndmitchell

src/Development/Shake/Internal/Core/Action.hs

@@ -477,6 +477,9 @@ unsafeExtraThread act = do
 
 
 -- | Execute a list of actions in parallel. In most cases 'need' will be more appropriate to benefit from parallelism.
+--   If the two types of 'Action' are different dependencies which ultimately boil down to 'apply',
+--   using 'Applicative' operations will still ensure the dependencies occur in parallel.
+--   The main use of this function is to run work that happens in an 'Action' in parallel.
 parallel :: [Action a] -> Action [a]
 -- Note: There is no parallel_ unlike sequence_ because there is no stack benefit to doing so
 parallel [] = pure []

src/Development/Shake/Internal/Core/Types.hs

@@ -58,6 +58,10 @@ import Prelude
 -- | The 'Action' monad, use 'liftIO' to raise 'IO' actions into it, and 'Development.Shake.need' to execute files.
 --   Action values are used by 'addUserRule' and 'action'. The 'Action' monad tracks the dependencies of a rule.
 --   To raise an exception call 'error', 'fail' or @'liftIO' . 'throwIO'@.
+--
+--   The 'Action' type is both a 'Monad' and 'Applicative'. Anything that is depended upon applicatively
+--   will have its dependencies run in parallel. For example @'need' [\"a\"] *> 'need [\"b\"]@ is equivalent
+--   to @'need' [\"a\", \"b\"]@.
 newtype Action a = Action {fromAction :: RAW ([String],[Key]) [Value] Global Local a}
     deriving (Functor, Applicative, Monad, MonadIO, Typeable, Semigroup, Monoid, MonadFail)