diff --git a/XMonad/Layout/PerScreen.hs b/XMonad/Layout/PerScreen.hs
index cacd4cb341..09ea179c2b 100644
--- a/XMonad/Layout/PerScreen.hs
+++ b/XMonad/Layout/PerScreen.hs
@@ -52,10 +52,15 @@ import Data.List (find)
 -- 'onScreen' can also be used inside other layout combinators, although the
 -- result may be confusing.
 
+-- | Specify a layout to run on a given screen.
 onScreen :: (LayoutClass l1 a, LayoutClass l2 a)
          => ScreenId -> l1 a -> l2 a -> OnScreen l1 l2 a
 onScreen s = onScreens [s]
 
+-- | Specify a layout to run on a list of screens.
+--   Note that this works by 'ScreenId'. It has a 'Num' instance, so literal
+--   screen numbers will work as expected, but if you use a binding you need
+--   to use the 'S' constructor.
 onScreens :: (LayoutClass l1 a, LayoutClass l2 a)
           => [ScreenId] -> l1 a -> l2 a -> OnScreen l1 l2 a
 onScreens ss l1 l2 = OnScreen ss l1 l2 False -- @@@ is this right?