Properly escape character literals in Haddocks

Character literals in Haddock should not be written as plain `'\n'` since
single quotes are for linking identifiers. Besides, since we want the
character literal to be monospaced, we really should use `@\'\\n\'@`.

[skip ci]

7 files changed, 19 insertions, 19 deletions

diff --git a/compiler/basicTypes/Literal.hs b/compiler/basicTypes/Literal.hs
index aa1dc3f9f3..bfc3783d2b 100644
--- a/compiler/basicTypes/Literal.hs
+++ b/compiler/basicTypes/Literal.hs
@@ -114,7 +114,7 @@ data Literal
 
   | LitString  ByteString       -- ^ A string-literal: stored and emitted
                                 -- UTF-8 encoded, we'll arrange to decode it
-                                -- at runtime.  Also emitted with a @'\0'@
+                                -- at runtime.  Also emitted with a @\'\\0\'@
                                 -- terminator. Create with 'mkLitString'
 
   | LitNullAddr                 -- ^ The @NULL@ pointer, the only pointer value
diff --git a/compiler/utils/StringBuffer.hs b/compiler/utils/StringBuffer.hs
index a5fc4e7f12..64578bffde 100644
--- a/compiler/utils/StringBuffer.hs
+++ b/compiler/utils/StringBuffer.hs
@@ -81,7 +81,7 @@ data StringBuffer
      cur :: {-# UNPACK #-} !Int         -- current pos
   }
   -- The buffer is assumed to be UTF-8 encoded, and furthermore
-  -- we add three '\0' bytes to the end as sentinels so that the
+  -- we add three @\'\\0\'@ bytes to the end as sentinels so that the
   -- decoder doesn't have to check for overflow at every single byte
   -- of a multibyte sequence.
 
@@ -187,7 +187,7 @@ stringToStringBuffer str =
 -- the remaining portion (analogous to 'Data.List.uncons').  __Warning:__ The
 -- behavior is undefined if the 'StringBuffer' is empty.  The result shares
 -- the same buffer as the original.  Similar to 'utf8DecodeChar', if the
--- character cannot be decoded as UTF-8, '\0' is returned.
+-- character cannot be decoded as UTF-8, @\'\\0\'@ is returned.
 {-# INLINE nextChar #-}
 nextChar :: StringBuffer -> (Char,StringBuffer)
 nextChar (StringBuffer buf len (I# cur#)) =
@@ -202,7 +202,7 @@ nextChar (StringBuffer buf len (I# cur#)) =
 -- | Return the first UTF-8 character of a nonempty 'StringBuffer' (analogous
 -- to 'Data.List.head').  __Warning:__ The behavior is undefined if the
 -- 'StringBuffer' is empty.  Similar to 'utf8DecodeChar', if the character
--- cannot be decoded as UTF-8, '\0' is returned.
+-- cannot be decoded as UTF-8, @\'\\0\'@ is returned.
 currentChar :: StringBuffer -> Char
 currentChar = fst . nextChar
 
@@ -285,7 +285,7 @@ skipToLine !line !len !op0 = go 1 op0
 
 -- | Decode the first @n@ bytes of a 'StringBuffer' as UTF-8 into a 'String'.
 -- Similar to 'utf8DecodeChar', if the character cannot be decoded as UTF-8,
--- they will be replaced with '\0'.
+-- they will be replaced with @\'\\0\'@.
 lexemeToString :: StringBuffer
                -> Int                   -- ^ @n@, the number of bytes
                -> String
diff --git a/libraries/base/GHC/IO/Device.hs b/libraries/base/GHC/IO/Device.hs
index e33dcd02b1..024ff7bbbb 100644
--- a/libraries/base/GHC/IO/Device.hs
+++ b/libraries/base/GHC/IO/Device.hs
@@ -139,7 +139,7 @@ data IODeviceType
   = Directory -- ^ The standard libraries do not have direct support
               -- for this device type, but a user implementation is
               -- expected to provide a list of file names in
-              -- the directory, in any order, separated by @'\0'@
+              -- the directory, in any order, separated by @\'\\0\'@
               -- characters, excluding the @"."@ and @".."@ names. See
               -- also 'System.Directory.getDirectoryContents'.  Seek
               -- operations are not supported on directories (other
diff --git a/libraries/base/GHC/IO/Encoding.hs b/libraries/base/GHC/IO/Encoding.hs
index b734f00f5b..735c1b0a37 100644
--- a/libraries/base/GHC/IO/Encoding.hs
+++ b/libraries/base/GHC/IO/Encoding.hs
@@ -57,7 +57,7 @@ import System.IO.Unsafe (unsafePerformIO)
 -- | The Latin1 (ISO8859-1) encoding.  This encoding maps bytes
 -- directly to the first 256 Unicode code points, and is thus not a
 -- complete Unicode encoding.  An attempt to write a character greater than
--- '\255' to a 'System.IO.Handle' using the 'latin1' encoding will result in an
+-- @\'\\255\'@ to a 'System.IO.Handle' using the 'latin1' encoding will result in an
 -- error.
 latin1  :: TextEncoding
 latin1 = Latin1.latin1_checked
diff --git a/libraries/base/GHC/IO/Handle/Types.hs b/libraries/base/GHC/IO/Handle/Types.hs
index f994e92b97..aeb72af847 100644
--- a/libraries/base/GHC/IO/Handle/Types.hs
+++ b/libraries/base/GHC/IO/Handle/Types.hs
@@ -351,8 +351,8 @@ and hence it is only possible on a seekable Handle.
 -- Newline translation
 
 -- | The representation of a newline in the external file or stream.
-data Newline = LF    -- ^ '\n'
-             | CRLF  -- ^ '\r\n'
+data Newline = LF    -- ^ @\'\\n\'@
+             | CRLF  -- ^ @\'\\r\\n\'@
              deriving ( Eq   -- ^ @since 4.2.0.0
                       , Ord  -- ^ @since 4.3.0.0
                       , Read -- ^ @since 4.3.0.0
@@ -361,9 +361,9 @@ data Newline = LF    -- ^ '\n'
 
 -- | Specifies the translation, if any, of newline characters between
 -- internal Strings and the external file or stream.  Haskell Strings
--- are assumed to represent newlines with the '\n' character; the
--- newline mode specifies how to translate '\n' on output, and what to
--- translate into '\n' on input.
+-- are assumed to represent newlines with the @\'\\n\'@ character; the
+-- newline mode specifies how to translate @\'\\n\'@ on output, and what to
+-- translate into @\'\\n\'@ on input.
 data NewlineMode
   = NewlineMode { inputNL :: Newline,
                     -- ^ the representation of newlines on input
@@ -385,7 +385,7 @@ nativeNewline = CRLF
 nativeNewline = LF
 #endif
 
--- | Map '\r\n' into '\n' on input, and '\n' to the native newline
+-- | Map @\'\\r\\n\'@ into @\'\\n\'@ on input, and @\'\\n\'@ to the native newline
 -- represetnation on output.  This mode can be used on any platform, and
 -- works with text files using any newline convention.  The downside is
 -- that @readFile >>= writeFile@ might yield a different file.
diff --git a/libraries/base/GHC/ResponseFile.hs b/libraries/base/GHC/ResponseFile.hs
index 804bd44ff7..1b6c2b8647 100644
--- a/libraries/base/GHC/ResponseFile.hs
+++ b/libraries/base/GHC/ResponseFile.hs
@@ -100,7 +100,7 @@ unescapeArgs = filter (not . null) . unescape
 escapeArgs :: [String] -> String
 escapeArgs = unlines . map escapeArg
 
--- | Arguments which look like '@foo' will be replaced with the
+-- | Arguments which look like @\@foo@ will be replaced with the
 -- contents of file @foo@. A gcc-like syntax for response files arguments
 -- is expected.  This must re-constitute the argument list by doing an
 -- inverse of the escaping mechanism done by the calling-program side.
diff --git a/libraries/base/System/IO.hs b/libraries/base/System/IO.hs
index 900963a045..1fc39bed25 100644
--- a/libraries/base/System/IO.hs
+++ b/libraries/base/System/IO.hs
@@ -197,19 +197,19 @@ module System.IO (
     -- * Newline conversion
 
     -- | In Haskell, a newline is always represented by the character
-    -- '\n'.  However, in files and external character streams, a
+    -- @\'\\n\'@.  However, in files and external character streams, a
     -- newline may be represented by another character sequence, such
-    -- as '\r\n'.
+    -- as @\'\\r\\n\'@.
     --
     -- A text-mode 'Handle' has an associated 'NewlineMode' that
     -- specifies how to transate newline characters.  The
     -- 'NewlineMode' specifies the input and output translation
-    -- separately, so that for instance you can translate '\r\n'
-    -- to '\n' on input, but leave newlines as '\n' on output.
+    -- separately, so that for instance you can translate @\'\\r\\n\'@
+    -- to @\'\\n\'@ on input, but leave newlines as @\'\\n\'@ on output.
     --
     -- The default 'NewlineMode' for a 'Handle' is
     -- 'nativeNewlineMode', which does no translation on Unix systems,
-    -- but translates '\r\n' to '\n' and back on Windows.
+    -- but translates @\'\\r\\n\'@ to @\'\\n\'@ and back on Windows.
     --
     -- Binary-mode 'Handle's do no newline translation at all.
     --