Add pprDefiniteTrace and use it
[ghc-hetmet.git] / compiler / utils / Outputable.lhs
index 61ad4dd..c4a685b 100644 (file)
@@ -3,69 +3,96 @@
 % (c) The GRASP Project, Glasgow University, 1992-1998
 %
 
-Outputable: defines classes for pretty-printing and forcing, both
-forms of ``output.''
-
 \begin{code}
+-- | This module defines classes and functions for pretty-printing. It also
+-- exports a number of helpful debugging and other utilities such as 'trace' and 'panic'.
+--
+-- The interface to this module is very similar to the standard Hughes-PJ pretty printing
+-- module, except that it exports a number of additional functions that are rarely used,
+-- and works over the 'SDoc' type.
 module Outputable (
-       Outputable(..), OutputableBndr(..),     -- Class
-
-       BindingSite(..),
+       -- * Type classes
+       Outputable(..), OutputableBndr(..),
 
-       PprStyle, CodeStyle(..), PrintUnqualified, alwaysQualify, neverQualify,
-        QualifyName(..),
-       getPprStyle, withPprStyle, withPprStyleDoc, 
-       pprDeeper, pprDeeperList, pprSetDepth,
-       codeStyle, userStyle, debugStyle, dumpStyle, asmStyle,
-       ifPprDebug, qualName, qualModule,
-       mkErrStyle, defaultErrStyle, defaultDumpStyle, defaultUserStyle,
-        mkUserStyle,
-
-       SDoc,           -- Abstract
+        -- * Pretty printing combinators
+       SDoc,
        docToSDoc,
-       interppSP, interpp'SP, pprQuotedList, pprWithCommas,
+       interppSP, interpp'SP, pprQuotedList, pprWithCommas, quotedListWithOr,
        empty, nest,
-       text, char, ftext, ptext,
+       char,
+       text, ftext, ptext,
        int, integer, float, double, rational,
        parens, cparen, brackets, braces, quotes, doubleQuotes, angleBrackets,
-       semi, comma, colon, dcolon, space, equals, dot, arrow,
+       semi, comma, colon, dcolon, space, equals, dot, arrow, darrow,
        lparen, rparen, lbrack, rbrack, lbrace, rbrace, underscore,
+       blankLine,
        (<>), (<+>), hcat, hsep, 
-       ($$), ($+$), vcat, 
+       ($$), ($+$), vcat,
        sep, cat, 
        fsep, fcat, 
-       hang, punctuate,
+       hang, punctuate, ppWhen, ppUnless,
        speakNth, speakNTimes, speakN, speakNOf, plural,
 
-       printSDoc, printErrs, hPrintDump, printDump,
+        -- * Converting 'SDoc' into strings and outputing it
+       printSDoc, printErrs, printOutput, hPrintDump, printDump,
        printForC, printForAsm, printForUser, printForUserPartWay,
        pprCode, mkCodeStyle,
-       showSDoc, showSDocForUser, showSDocDebug, showSDocDump,
+       showSDoc, showSDocOneLine,
+        showSDocForUser, showSDocDebug, showSDocDump, showSDocDumpOneLine,
+        showPpr,
        showSDocUnqual, showsPrecSDoc,
-       pprHsChar, pprHsString,
 
-       -- error handling
-       pprPanic, assertPprPanic, pprPanicFastInt, pprPgmError, 
-       pprTrace, warnPprTrace,
-       trace, pgmError, panic, panicFastInt, assertPanic
+       pprInfixVar, pprPrefixVar,
+       pprHsChar, pprHsString, pprHsInfix, pprHsVar,
+        pprFastFilePath,
+
+        -- * Controlling the style in which output is printed
+       BindingSite(..),
+
+       PprStyle, CodeStyle(..), PrintUnqualified, alwaysQualify, neverQualify,
+        QualifyName(..),
+       getPprStyle, withPprStyle, withPprStyleDoc, 
+       pprDeeper, pprDeeperList, pprSetDepth,
+       codeStyle, userStyle, debugStyle, dumpStyle, asmStyle,
+       ifPprDebug, qualName, qualModule,
+       mkErrStyle, defaultErrStyle, defaultDumpStyle, defaultUserStyle,
+        mkUserStyle, cmdlineParserStyle, Depth(..),
+       
+       -- * Error handling and debugging utilities
+       pprPanic, pprSorry, assertPprPanic, pprPanicFastInt, pprPgmError, 
+       pprTrace, pprDefiniteTrace, warnPprTrace,
+       trace, pgmError, panic, sorry, panicFastInt, assertPanic
     ) where
 
 import {-# SOURCE #-}  Module( Module, ModuleName, moduleName )
 import {-# SOURCE #-}  OccName( OccName )
 
 import StaticFlags
-import FastString
+import FastString 
 import FastTypes
 import qualified Pretty
 import Pretty          ( Doc, Mode(..) )
 import Panic
 
-import Data.Word       ( Word32 )
+import Data.Char
+import qualified Data.Map as M
+import qualified Data.IntMap as IM
+import Data.Word
 import System.IO       ( Handle, stderr, stdout, hFlush )
-import Data.Char        ( ord )
+import System.FilePath
+
+
+#if __GLASGOW_HASKELL__ >= 701
+import GHC.Show         ( showMultiLineString )
+#else
+showMultiLineString :: String -> [String]
+-- Crude version
+showMultiLineString s = [ showList s "" ]
+#endif
 \end{code}
 
 
+
 %************************************************************************
 %*                                                                     *
 \subsection{The @PprStyle@ data type}
@@ -114,6 +141,7 @@ data Depth = AllTheWay
 -- in source code, names are qualified by ModuleNames.
 type QueryQualifyName = Module -> OccName -> QualifyName
 
+-- See Note [Printing original names] in HscTypes
 data QualifyName                        -- given P:M.T
         = NameUnqual                    -- refer to it as "T"
         | NameQual ModuleName           -- refer to it as "X.T" for the supplied X
@@ -143,9 +171,7 @@ alwaysQualifyModules _ = True
 neverQualifyModules :: QueryQualifyModule
 neverQualifyModules _ = False
 
-type QueryQualifies = (QueryQualifyName, QueryQualifyModule)
-
-alwaysQualify, neverQualify :: QueryQualifies
+alwaysQualify, neverQualify :: PrintUnqualified
 alwaysQualify = (alwaysQualifyNames, alwaysQualifyModules)
 neverQualify  = (neverQualifyNames,  neverQualifyModules)
 
@@ -168,10 +194,13 @@ defaultErrStyle
   | opt_PprStyle_Debug   = mkUserStyle alwaysQualify AllTheWay
   | otherwise            = mkUserStyle alwaysQualify (PartWay opt_PprUserLength)
 
-mkUserStyle :: QueryQualifies -> Depth -> PprStyle
+mkUserStyle :: PrintUnqualified -> Depth -> PprStyle
 mkUserStyle unqual depth
    | opt_PprStyle_Debug = PprDebug
    | otherwise          = PprUser unqual depth
+
+cmdlineParserStyle :: PprStyle
+cmdlineParserStyle = PprUser alwaysQualify AllTheWay
 \end{code}
 
 Orthogonal to the above printing styles are (possibly) some
@@ -215,9 +244,9 @@ pprDeeperList f ds (PprUser q (PartWay n))
 pprDeeperList f ds other_sty
   = f ds other_sty
 
-pprSetDepth :: Int -> SDoc -> SDoc
-pprSetDepth  n d (PprUser q _) = d (PprUser q (PartWay n))
-pprSetDepth _n d other_sty     = d other_sty
+pprSetDepth :: Depth -> SDoc -> SDoc
+pprSetDepth depth  doc (PprUser q _) = doc (PprUser q depth)
+pprSetDepth _depth doc other_sty     = doc other_sty
 
 getPprStyle :: (PprStyle -> SDoc) -> SDoc
 getPprStyle df sty = df sty sty
@@ -270,6 +299,9 @@ printErrs :: Doc -> IO ()
 printErrs doc = do Pretty.printDoc PageMode stderr doc
                   hFlush stderr
 
+printOutput :: Doc -> IO ()
+printOutput doc = Pretty.printDoc PageMode stdout doc
+
 printDump :: SDoc -> IO ()
 printDump doc = hPrintDump stdout doc
 
@@ -278,7 +310,7 @@ hPrintDump h doc = do
    Pretty.printDoc PageMode h (better_doc defaultDumpStyle)
    hFlush h
  where
-   better_doc = doc $$ text ""
+   better_doc = doc $$ blankLine
 
 printForUser :: Handle -> PrintUnqualified -> SDoc -> IO ()
 printForUser handle unqual doc 
@@ -305,23 +337,35 @@ mkCodeStyle = PprCode
 -- However, Doc *is* an instance of Show
 -- showSDoc just blasts it out as a string
 showSDoc :: SDoc -> String
-showSDoc d = show (d defaultUserStyle)
+showSDoc d = Pretty.showDocWith PageMode (d defaultUserStyle)
+
+-- This shows an SDoc, but on one line only. It's cheaper than a full
+-- showSDoc, designed for when we're getting results like "Foo.bar"
+-- and "foo{uniq strictness}" so we don't want fancy layout anyway.
+showSDocOneLine :: SDoc -> String
+showSDocOneLine d = Pretty.showDocWith PageMode (d defaultUserStyle)
 
 showSDocForUser :: PrintUnqualified -> SDoc -> String
 showSDocForUser unqual doc = show (doc (mkUserStyle unqual AllTheWay))
 
 showSDocUnqual :: SDoc -> String
--- Only used in the gruesome HsExpr.isOperator
+-- Only used in the gruesome isOperator
 showSDocUnqual d = show (d (mkUserStyle neverQualify AllTheWay))
 
 showsPrecSDoc :: Int -> SDoc -> ShowS
 showsPrecSDoc p d = showsPrec p (d defaultUserStyle)
 
 showSDocDump :: SDoc -> String
-showSDocDump d = show (d PprDump)
+showSDocDump d = Pretty.showDocWith PageMode (d PprDump)
+
+showSDocDumpOneLine :: SDoc -> String
+showSDocDumpOneLine d = Pretty.showDocWith OneLineMode (d PprDump)
 
 showSDocDebug :: SDoc -> String
 showSDocDebug d = show (d PprDebug)
+
+showPpr :: Outputable a => a -> String
+showPpr = showSDoc . ppr
 \end{code}
 
 \begin{code}
@@ -329,8 +373,8 @@ docToSDoc :: Doc -> SDoc
 docToSDoc d = \_ -> d
 
 empty    :: SDoc
-text     :: String     -> SDoc
 char     :: Char       -> SDoc
+text     :: String     -> SDoc
 ftext    :: FastString -> SDoc
 ptext    :: LitString  -> SDoc
 int      :: Int        -> SDoc
@@ -340,8 +384,8 @@ double   :: Double     -> SDoc
 rational :: Rational   -> SDoc
 
 empty _sty      = Pretty.empty
-text s _sty     = Pretty.text s
 char c _sty     = Pretty.char c
+text s _sty     = Pretty.text s
 ftext s _sty    = Pretty.ftext s
 ptext s _sty    = Pretty.ptext s
 int n _sty      = Pretty.int n
@@ -372,26 +416,37 @@ quotes d sty = case show pp_d of
               pp_d = d sty
 
 semi, comma, colon, equals, space, dcolon, arrow, underscore, dot :: SDoc
-lparen, rparen, lbrack, rbrack, lbrace, rbrace :: SDoc
-
-semi _sty   = Pretty.semi
-comma _sty  = Pretty.comma
-colon _sty  = Pretty.colon
-equals _sty = Pretty.equals
-space _sty  = Pretty.space
-dcolon _sty = Pretty.ptext (sLit "::")
-arrow  _sty = Pretty.ptext (sLit "->")
-underscore  = char '_'
-dot        = char '.'
-lparen _sty = Pretty.lparen
-rparen _sty = Pretty.rparen
-lbrack _sty = Pretty.lbrack
-rbrack _sty = Pretty.rbrack
-lbrace _sty = Pretty.lbrace
-rbrace _sty = Pretty.rbrace
+darrow, lparen, rparen, lbrack, rbrack, lbrace, rbrace, blankLine :: SDoc
+
+blankLine _sty = Pretty.ptext (sLit "")
+dcolon _sty    = Pretty.ptext (sLit "::")
+arrow  _sty    = Pretty.ptext (sLit "->")
+darrow _sty    = Pretty.ptext (sLit "=>")
+semi _sty      = Pretty.semi
+comma _sty     = Pretty.comma
+colon _sty     = Pretty.colon
+equals _sty    = Pretty.equals
+space _sty     = Pretty.space
+underscore     = char '_'
+dot           = char '.'
+lparen _sty    = Pretty.lparen
+rparen _sty    = Pretty.rparen
+lbrack _sty    = Pretty.lbrack
+rbrack _sty    = Pretty.rbrack
+lbrace _sty    = Pretty.lbrace
+rbrace _sty    = Pretty.rbrace
 
 nest :: Int -> SDoc -> SDoc
-(<>), (<+>), ($$), ($+$) :: SDoc -> SDoc -> SDoc
+-- ^ Indent 'SDoc' some specified amount
+(<>) :: SDoc -> SDoc -> SDoc
+-- ^ Join two 'SDoc' together horizontally without a gap
+(<+>) :: SDoc -> SDoc -> SDoc
+-- ^ Join two 'SDoc' together horizontally with a gap between them
+($$) :: SDoc -> SDoc -> SDoc
+-- ^ Join two 'SDoc' together vertically; if there is 
+-- no vertical overlap it "dovetails" the two onto one line
+($+$) :: SDoc -> SDoc -> SDoc
+-- ^ Join two 'SDoc' together vertically
 
 nest n d sty    = Pretty.nest n (d sty)
 (<>) d1 d2 sty  = (Pretty.<>)  (d1 sty) (d2 sty)
@@ -399,7 +454,21 @@ nest n d sty    = Pretty.nest n (d sty)
 ($$) d1 d2 sty  = (Pretty.$$)  (d1 sty) (d2 sty)
 ($+$) d1 d2 sty = (Pretty.$+$) (d1 sty) (d2 sty)
 
-hcat, hsep, vcat, sep, cat, fsep, fcat :: [SDoc] -> SDoc
+hcat :: [SDoc] -> SDoc
+-- ^ Concatenate 'SDoc' horizontally
+hsep :: [SDoc] -> SDoc
+-- ^ Concatenate 'SDoc' horizontally with a space between each one
+vcat :: [SDoc] -> SDoc
+-- ^ Concatenate 'SDoc' vertically with dovetailing
+sep :: [SDoc] -> SDoc
+-- ^ Separate: is either like 'hsep' or like 'vcat', depending on what fits
+cat :: [SDoc] -> SDoc
+-- ^ Catenate: is either like 'hcat' or like 'vcat', depending on what fits
+fsep :: [SDoc] -> SDoc
+-- ^ A paragraph-fill combinator. It's much like sep, only it
+-- keeps fitting things on one line until it can't fit any more.
+fcat :: [SDoc] -> SDoc
+-- ^ This behaves like 'fsep', but it uses '<>' for horizontal conposition rather than '<+>'
 
 
 hcat ds sty = Pretty.hcat [d sty | d <- ds]
@@ -410,16 +479,27 @@ cat ds sty  = Pretty.cat  [d sty | d <- ds]
 fsep ds sty = Pretty.fsep [d sty | d <- ds]
 fcat ds sty = Pretty.fcat [d sty | d <- ds]
 
-hang :: SDoc -> Int -> SDoc -> SDoc
-
+hang :: SDoc  -- ^ The header
+      -> Int  -- ^ Amount to indent the hung body
+      -> SDoc -- ^ The hung body, indented and placed below the header
+      -> SDoc
 hang d1 n d2 sty   = Pretty.hang (d1 sty) n (d2 sty)
 
-punctuate :: SDoc -> [SDoc] -> [SDoc]
+punctuate :: SDoc   -- ^ The punctuation
+          -> [SDoc] -- ^ The list that will have punctuation added between every adjacent pair of elements
+          -> [SDoc] -- ^ Punctuated list
 punctuate _ []     = []
 punctuate p (d:ds) = go d ds
                   where
                     go d [] = [d]
                     go d (e:es) = (d <> p) : go e es
+
+ppWhen, ppUnless :: Bool -> SDoc -> SDoc
+ppWhen True  doc = doc
+ppWhen False _   = empty
+
+ppUnless True  _   = empty
+ppUnless False doc = doc
 \end{code}
 
 
@@ -430,6 +510,7 @@ punctuate p (d:ds) = go d ds
 %************************************************************************
 
 \begin{code}
+-- | Class designating that some type has an 'SDoc' representation
 class Outputable a where
        ppr :: a -> SDoc
 \end{code}
@@ -442,9 +523,15 @@ instance Outputable Bool where
 instance Outputable Int where
    ppr n = int n
 
+instance Outputable Word16 where
+   ppr n = integer $ fromIntegral n
+
 instance Outputable Word32 where
    ppr n = integer $ fromIntegral n
 
+instance Outputable Word where
+   ppr n = integer $ fromIntegral n
+
 instance Outputable () where
    ppr _ = text "()"
 
@@ -489,8 +576,12 @@ instance (Outputable a, Outputable b, Outputable c, Outputable d, Outputable e)
 instance Outputable FastString where
     ppr fs = ftext fs          -- Prints an unadorned string,
                                -- no double quotes or anything
-\end{code}
 
+instance (Outputable key, Outputable elt) => Outputable (M.Map key elt) where
+    ppr m = ppr (M.toList m)
+instance (Outputable elt) => Outputable (IM.IntMap elt) where
+    ppr m = ppr (IM.toList m)
+\end{code}
 
 %************************************************************************
 %*                                                                     *
@@ -498,23 +589,19 @@ instance Outputable FastString where
 %*                                                                     *
 %************************************************************************
 
-When we print a binder, we often want to print its type too.
-The @OutputableBndr@ class encapsulates this idea.
-
-@BindingSite@ is used to tell the thing that prints binder what
-language construct is binding the identifier.  This can be used
-to decide how much info to print.
-
 \begin{code}
+-- | 'BindingSite' is used to tell the thing that prints binder what
+-- language construct is binding the identifier.  This can be used
+-- to decide how much info to print.
 data BindingSite = LambdaBind | CaseBind | LetBind
 
+-- | When we print a binder, we often want to print its type too.
+-- The @OutputableBndr@ class encapsulates this idea.
 class Outputable a => OutputableBndr a where
    pprBndr :: BindingSite -> a -> SDoc
    pprBndr _b x = ppr x
 \end{code}
 
-
-
 %************************************************************************
 %*                                                                     *
 \subsection{Random printing helpers}
@@ -522,18 +609,56 @@ class Outputable a => OutputableBndr a where
 %************************************************************************
 
 \begin{code}
--- We have 31-bit Chars and will simply use Show instances
--- of Char and String.
+-- We have 31-bit Chars and will simply use Show instances of Char and String.
 
+-- | Special combinator for showing character literals.
 pprHsChar :: Char -> SDoc
 pprHsChar c | c > '\x10ffff' = char '\\' <> text (show (fromIntegral (ord c) :: Word32))
             | otherwise      = text (show c)
 
+-- | Special combinator for showing string literals.
 pprHsString :: FastString -> SDoc
-pprHsString fs = text (show (unpackFS fs))
+pprHsString fs = vcat (map text (showMultiLineString (unpackFS fs)))
+
+---------------------
+-- Put a name in parens if it's an operator
+pprPrefixVar :: Bool -> SDoc -> SDoc
+pprPrefixVar is_operator pp_v
+  | is_operator = parens pp_v
+  | otherwise  = pp_v
+
+-- Put a name in backquotes if it's not an operator
+pprInfixVar :: Bool -> SDoc -> SDoc
+pprInfixVar is_operator pp_v 
+  | is_operator = pp_v
+  | otherwise   = char '`' <> pp_v <> char '`'
+
+---------------------
+-- pprHsVar and pprHsInfix use the gruesome isOperator, which
+-- in turn uses (showSDoc (ppr v)), rather than isSymOcc (getOccName v).
+-- Reason: it means that pprHsVar doesn't need a NamedThing context,
+--         which none of the HsSyn printing functions do
+pprHsVar, pprHsInfix :: Outputable name => name -> SDoc
+pprHsVar   v = pprPrefixVar (isOperator pp_v) pp_v  
+            where pp_v = ppr v
+pprHsInfix v = pprInfixVar  (isOperator pp_v) pp_v
+            where pp_v = ppr v
+
+isOperator :: SDoc -> Bool
+isOperator ppr_v 
+  = case showSDocUnqual ppr_v of
+        ('(':_)   -> False              -- (), (,) etc
+        ('[':_)   -> False              -- []
+        ('$':c:_) -> not (isAlpha c)    -- Don't treat $d as an operator
+        (':':c:_) -> not (isAlpha c)    -- Don't treat :T as an operator
+        ('_':_)   -> False              -- Not an operator
+        (c:_)     -> not (isAlpha c)    -- Starts with non-alpha
+        _         -> False
+
+pprFastFilePath :: FastString -> SDoc
+pprFastFilePath path = text $ normalise $ unpackFS path
 \end{code}
 
-
 %************************************************************************
 %*                                                                     *
 \subsection{Other helper functions}
@@ -541,18 +666,33 @@ pprHsString fs = text (show (unpackFS fs))
 %************************************************************************
 
 \begin{code}
-pprWithCommas :: (a -> SDoc) -> [a] -> SDoc
+pprWithCommas :: (a -> SDoc) -- ^ The pretty printing function to use
+              -> [a]         -- ^ The things to be pretty printed
+              -> SDoc        -- ^ 'SDoc' where the things have been pretty printed,
+                             -- comma-separated and finally packed into a paragraph.
 pprWithCommas pp xs = fsep (punctuate comma (map pp xs))
 
+-- | Returns the seperated concatenation of the pretty printed things.
 interppSP  :: Outputable a => [a] -> SDoc
 interppSP  xs = sep (map ppr xs)
 
+-- | Returns the comma-seperated concatenation of the pretty printed things.
 interpp'SP :: Outputable a => [a] -> SDoc
 interpp'SP xs = sep (punctuate comma (map ppr xs))
 
+-- | Returns the comma-seperated concatenation of the quoted pretty printed things.
+--
+-- > [x,y,z]  ==>  `x', `y', `z'
 pprQuotedList :: Outputable a => [a] -> SDoc
--- [x,y,z]  ==>  `x', `y', `z'
-pprQuotedList xs = hsep (punctuate comma (map (quotes . ppr) xs))
+pprQuotedList = quotedList . map ppr
+
+quotedList :: [SDoc] -> SDoc
+quotedList xs = hsep (punctuate comma (map quotes xs))
+
+quotedListWithOr :: [SDoc] -> SDoc
+-- [x,y,z]  ==>  `x', `y' or `z'
+quotedListWithOr xs@(_:_:_) = quotedList (init xs) <+> ptext (sLit "or") <+> quotes (last xs)
+quotedListWithOr xs = quotedList xs
 \end{code}
 
 
@@ -562,10 +702,12 @@ pprQuotedList xs = hsep (punctuate comma (map (quotes . ppr) xs))
 %*                                                                     *
 %************************************************************************
 
-@speakNth@ converts an integer to a verbal index; eg 1 maps to
-``first'' etc.
-
 \begin{code}
+-- | Converts an integer to a verbal index:
+--
+-- > speakNth 1 = text "first"
+-- > speakNth 5 = text "fifth"
+-- > speakNth 21 = text "21st"
 speakNth :: Int -> SDoc
 speakNth 1 = ptext (sLit "first")
 speakNth 2 = ptext (sLit "second")
@@ -583,6 +725,11 @@ speakNth n = hcat [ int n, text suffix ]
 
     last_dig = n `rem` 10
 
+-- | Converts an integer to a verbal multiplicity:
+-- 
+-- > speakN 0 = text "none"
+-- > speakN 5 = text "five"
+-- > speakN 10 = text "10"
 speakN :: Int -> SDoc
 speakN 0 = ptext (sLit "none") -- E.g.  "he has none"
 speakN 1 = ptext (sLit "one")  -- E.g.  "he has one"
@@ -593,16 +740,32 @@ speakN 5 = ptext (sLit "five")
 speakN 6 = ptext (sLit "six")
 speakN n = int n
 
+-- | Converts an integer and object description to a statement about the
+-- multiplicity of those objects:
+--
+-- > speakNOf 0 (text "melon") = text "no melons"
+-- > speakNOf 1 (text "melon") = text "one melon"
+-- > speakNOf 3 (text "melon") = text "three melons"
 speakNOf :: Int -> SDoc -> SDoc
-speakNOf 0 d = ptext (sLit "no") <+> d <> char 's'     -- E.g. "no arguments"
+speakNOf 0 d = ptext (sLit "no") <+> d <> char 's'
 speakNOf 1 d = ptext (sLit "one") <+> d                        -- E.g. "one argument"
 speakNOf n d = speakN n <+> d <> char 's'              -- E.g. "three arguments"
 
+-- | Converts a strictly positive integer into a number of times:
+--
+-- > speakNTimes 1 = text "once"
+-- > speakNTimes 2 = text "twice"
+-- > speakNTimes 4 = text "4 times"
 speakNTimes :: Int {- >=1 -} -> SDoc
 speakNTimes t | t == 1            = ptext (sLit "once")
               | t == 2            = ptext (sLit "twice")
               | otherwise  = speakN t <+> ptext (sLit "times")
 
+-- | Determines the pluralisation suffix appropriate for the length of a list:
+--
+-- > plural [] = char 's'
+-- > plural ["Hello"] = empty
+-- > plural ["Hello", "World"] = char 's'
 plural :: [a] -> SDoc
 plural [_] = empty  -- a bit frightening, but there you are
 plural _   = char 's'
@@ -616,27 +779,46 @@ plural _   = char 's'
 %************************************************************************
 
 \begin{code}
-pprPanic, pprPgmError :: String -> SDoc -> a
-pprTrace :: String -> SDoc -> a -> a
-pprPanic    = pprAndThen panic         -- Throw an exn saying "bug in GHC"
 
-pprPgmError = pprAndThen pgmError      -- Throw an exn saying "bug in pgm being compiled"
-                                       --      (used for unusual pgm errors)
+pprPanic :: String -> SDoc -> a
+-- ^ Throw an exception saying "bug in GHC"
+pprPanic    = pprAndThen panic
+
+pprSorry :: String -> SDoc -> a
+-- ^ Throw an exceptio saying "this isn't finished yet"
+pprSorry    = pprAndThen sorry
+
+
+pprPgmError :: String -> SDoc -> a
+-- ^ Throw an exception saying "bug in pgm being compiled" (used for unusual program errors)
+pprPgmError = pprAndThen pgmError
+
+
+pprTrace :: String -> SDoc -> a -> a
+-- ^ If debug output is on, show some 'SDoc' on the screen
 pprTrace str doc x
    | opt_NoDebugOutput = x
    | otherwise         = pprAndThen trace str doc x
 
+pprDefiniteTrace :: String -> SDoc -> a -> a
+-- ^ Same as pprTrace, but show even if -dno-debug-output is on
+pprDefiniteTrace str doc x = pprAndThen trace str doc x
+
 pprPanicFastInt :: String -> SDoc -> FastInt
+-- ^ Specialization of pprPanic that can be safely used with 'FastInt'
 pprPanicFastInt heading pretty_msg = panicFastInt (show (doc PprDebug))
                             where
                               doc = text heading <+> pretty_msg
 
+
 pprAndThen :: (String -> a) -> String -> SDoc -> a
 pprAndThen cont heading pretty_msg = cont (show (doc PprDebug))
     where
      doc = sep [text heading, nest 4 pretty_msg]
 
 assertPprPanic :: String -> Int -> SDoc -> a
+-- ^ Panic with an assertation failure, recording the given file and line number.
+-- Should typically be accessed with the ASSERT family of macros
 assertPprPanic file line msg
   = panic (show (doc PprDebug))
   where
@@ -646,10 +828,12 @@ assertPprPanic file line msg
                    msg]
 
 warnPprTrace :: Bool -> String -> Int -> SDoc -> a -> a
+-- ^ Just warn about an assertion failure, recording the given file and line number.
+-- Should typically be accessed with the WARN macros
 warnPprTrace _     _file _line _msg x | opt_NoDebugOutput = x
 warnPprTrace False _file _line _msg x = x
 warnPprTrace True   file  line  msg x
-  = trace (show (doc PprDebug)) x
+  = trace (show (doc defaultDumpStyle)) x
   where
     doc = sep [hsep [text "WARNING: file", text file, text "line", int line],
               msg]