X.A.SpawnOn: add docs

Add more documentation, including documentation from
X.U.SpawnOnWorkspace by Daniel Schoepe.

darcs-hash:20090204102424-3ebed-b91defc4d2c2736838f75d2ee7e9f98005903d27.gz

1 files changed, 38 insertions, 10 deletions

diff --git a/XMonad/Actions/SpawnOn.hs b/XMonad/Actions/SpawnOn.hs
index 923e7bb..80723a8 100644
--- a/XMonad/Actions/SpawnOn.hs
+++ b/XMonad/Actions/SpawnOn.hs
@@ -8,19 +8,15 @@
 -- Stability    : unstable
 -- Portability  : unportable
 --
--- This module provides helper functions to be used in @manageHook@. Here's
--- how you might use this:
+-- Provides a way to spawn an application on a specific workspace by using
+-- the _NET_WM_PID property that most windows set on creation. Hence this module
+-- won't work on applications that don't set this property.
 --
--- > import XMonad.Hooks.ManageHelpers
--- > main = do
--- >     sp <- mkSpawner
--- >     xmonad defaultConfig {
--- >         ...
--- >         manageHook = manageSpawn sp <+> manageHook defaultConfig
--- >         ...
--- >     }
+-----------------------------------------------------------------------------
 
 module XMonad.Actions.SpawnOn (
+    -- * Usage
+    -- $usage
     Spawner,
     mkSpawner,
     manageSpawn,
@@ -40,14 +36,38 @@ import XMonad.Hooks.ManageHelpers
 import XMonad.Prompt
 import XMonad.Prompt.Shell
 
+-- $usage
+-- You can use this module with the following in your @~\/.xmonad\/xmonad.hs@:
+--
+-- >    import XMonad.Actions.SpawnOn
+--
+-- >    main = do
+-- >      sp <- mkSpawner
+-- >      xmonad defaultConfig {
+-- >         ...
+-- >         manageHook = manageSpawn sp <+> manageHook defaultConfig
+-- >         ...
+-- >      }
+--
+-- To ensure that application appears on a workspace it was launched at, add keybindings like:
+--
+-- >  , ((mod1Mask,xK_o), spawnHere sp "urxvt")
+-- >  , ((mod1Mask,xK_s), shellPromptHere sp defaultXPConfig)
+--
+-- For detailed instructions on editing your key bindings, see
+-- "XMonad.Doc.Extending#Editing_key_bindings".
+
 newtype Spawner = Spawner {pidsRef :: IORef [(ProcessID, WorkspaceId)]}
 
 maxPids :: Int
 maxPids = 5
 
+-- | Create 'Spawner' which then has to be passed to other functions.
 mkSpawner :: (Functor m, MonadIO m) => m Spawner
 mkSpawner = io . fmap Spawner $ newIORef []
 
+-- | Provides a manage hook to react on process spawned with
+-- 'spawnOn', 'spawnHere' etc.
 manageSpawn :: Spawner -> ManageHook
 manageSpawn sp = do
     pids <- io . readIORef $ pidsRef sp
@@ -61,15 +81,23 @@ mkPrompt cb c = do
     cmds <- io $ getCommands
     mkXPrompt Shell c (getShellCompl cmds) cb
 
+-- | Replacement for Shell prompt ("XMonad.Prompt.Shell") which launches
+-- application on current workspace.
 shellPromptHere :: Spawner -> XPConfig -> X ()
 shellPromptHere sp = mkPrompt (spawnHere sp)
 
+-- | Replacement for Shell prompt ("XMonad.Prompt.Shell") which launches
+-- application on given workspace.
 shellPromptOn :: Spawner -> WorkspaceId -> XPConfig -> X ()
 shellPromptOn sp ws = mkPrompt (spawnOn sp ws)
 
+-- | Replacement for 'spawn' which launches
+-- application on current workspace.
 spawnHere :: Spawner -> String -> X ()
 spawnHere sp cmd = withWindowSet $ \ws -> spawnOn sp (W.currentTag ws) cmd
 
+-- | Replacement for 'spawn' which launches
+-- application on given workspace.
 spawnOn :: Spawner -> WorkspaceId -> String -> X ()
 spawnOn sp ws cmd = do
     p <- spawnPID cmd