document some PrettyPrint functions

src/Stack/PrettyPrint.hs

@@ -13,16 +13,16 @@ module Stack.PrettyPrint
     , prettyDebug, prettyInfo, prettyWarn, prettyError
     , prettyDebugL, prettyInfoL, prettyWarnL, prettyErrorL
     , prettyDebugS, prettyInfoS, prettyWarnS, prettyErrorS
-    , debugBracket
-      -- * Color utils
-      -- | These are preferred to colors directly, so that we can
-      -- encourage consistency of color meanings.
+      -- * Semantic styling functions
+      -- | These are preferred to styling or colors directly, so that we can
+      -- encourage consistency.
     , styleWarning, styleError, styleGood
     , styleShell, styleFile, styleDir
     , styleCurrent, styleTarget
     , displayMilliseconds
       -- * Formatting utils
     , bulletedList
+    , debugBracket
       -- * Re-exports from "Text.PrettyPrint.Leijen.Extended"
     , Display(..), AnsiDoc, AnsiAnn(..), HasAnsiAnn(..), Doc
     , nest, line, linebreak, group, softline, softbreak
@@ -92,12 +92,18 @@ prettyWarnS  = prettyWarnWith  [| flow |]
 prettyErrorS = prettyErrorWith [| flow |]
 -- End of aligned section
 
+-- | Use after a label and before the rest of what's being labelled for
+--   consistent spacing/indenting/etc.
+--
+--   For example this is used after "Warning:" in warning messages.
 indentAfterLabel :: Doc a -> Doc a
 indentAfterLabel = align
 
+-- | Make a 'Doc' from each word in a 'String'
 wordDocs :: String -> [Doc a]
 wordDocs = map fromString . words
 
+-- | Wordwrap a 'String'
 flow :: String -> Doc a
 flow = fillSep . wordDocs
 
@@ -121,27 +127,43 @@ debugBracket = do
             return x
       |]
 
+-- | Style an 'AnsiDoc' as an error. Should be used sparingly, not to style
+--   entire long messages. For example, it's used to style the "Error:"
+--   label for an error message, not the entire message.
 styleError :: AnsiDoc -> AnsiDoc
 styleError = dullred
 
+-- | Style an 'AnsiDoc' as a warning. Should be used sparingly, not to style
+--   entire long messages. For example, it's used to style the "Warning:"
+--   label for an error message, not the entire message.
 styleWarning :: AnsiDoc -> AnsiDoc
 styleWarning = yellow
 
+-- | Style an 'AnsiDoc' in a way to emphasize that it is a particularly good
+--   thing.
 styleGood :: AnsiDoc -> AnsiDoc
 styleGood = green
 
+-- | Style an 'AnsiDoc' as a shell command, i.e. when suggesting something
+--   to the user that should be typed in directly as written.
 styleShell :: AnsiDoc -> AnsiDoc
 styleShell = magenta
 
+-- | Style an 'AnsiDoc' as a filename. See 'styleDir' for directories.
 styleFile :: AnsiDoc -> AnsiDoc
 styleFile = bold . white
 
+-- | Style an 'AnsiDoc' as a directory name. See 'styleFile' for files.
 styleDir :: AnsiDoc -> AnsiDoc
 styleDir = bold . blue
 
+-- | Style an 'AnsiDoc' in a way that emphasizes that it is related to
+--   a current thing. For example, could be used when talking about the
+--   current package we're processing when outputting the name of it.
 styleCurrent :: AnsiDoc -> AnsiDoc
 styleCurrent = yellow
 
+-- TODO: figure out how to describe this
 styleTarget :: AnsiDoc -> AnsiDoc
 styleTarget = cyan
 
@@ -168,5 +190,6 @@ displayMilliseconds :: Clock.TimeSpec -> AnsiDoc
 displayMilliseconds t = green $
     (fromString . show . (`div` 10^(6 :: Int)) . Clock.toNanoSecs) t <> "ms"
 
+-- | Display a list of 'AnsiDoc', one per line, with bullets before each
 bulletedList :: [AnsiDoc] -> AnsiDoc
 bulletedList = mconcat . intersperse line . map ("*" <+>)