Haddock fixes (#560)

Tweaked documentation fixing Haddock markup. Mostly:

  * qualifying out-of-scope or ambiguous identifiers
  * properly escaping character literals in examples
  * several obvious typos

Author: harpocrates

Data/Graph.hs

@@ -412,7 +412,7 @@ graphFromEdges' x = (a,b) where
 -- > (graph, nodeFromVertex, vertexFromKey) = graphFromEdges []
 -- > graph = array (0,-1) []
 --
--- A graph where the out-list references unspecified nodes (@'c'@), these are
+-- A graph where the out-list references unspecified nodes (@\'c\'@), these are
 -- ignored.
 --
 -- > (graph, _, _) = graphFromEdges [("a", 'a', ['b']), ("b", 'b', ['c'])]

Data/IntMap/Internal.hs

@@ -984,8 +984,8 @@ alter f k Nil     = case f Nothing of
 -- 'alterF' is the most general operation for working with an individual
 -- key that may or may not be in a given map.
 --
--- Note: 'alterF' is a flipped version of the 'at' combinator from
--- 'Control.Lens.At'.
+-- Note: 'alterF' is a flipped version of the @at@ combinator from
+-- @Control.Lens.At@.
 --
 -- @since 0.5.8
 
@@ -1833,7 +1833,7 @@ traverseMaybeWithKey f = go
 
 -- | Merge two maps.
 --
--- @merge@ takes two 'WhenMissing' tactics, a 'WhenMatched' tactic
+-- 'merge' takes two 'WhenMissing' tactics, a 'WhenMatched' tactic
 -- and two maps. It uses the tactics to merge the maps. Its behavior
 -- is best understood via its fundamental tactics, 'mapMaybeMissing'
 -- and 'zipWithMaybeMatched'.
@@ -1850,22 +1850,22 @@ traverseMaybeWithKey f = go
 -- Take, for example,
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'), (3,'c'), (4, 'd')]
+-- m1 = [(0, \'a\'), (1, \'b\'), (3, \'c\'), (4, \'d\')]
 -- m2 = [(1, "one"), (2, "two"), (4, "three")]
 -- @
 --
--- @merge@ will first ''align'' these maps by key:
+-- 'merge' will first \"align\" these maps by key:
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'),               (3,'c'), (4, 'd')]
--- m2 =           [(1, "one"), (2, "two"),          (4, "three")]
+-- m1 = [(0, \'a\'), (1, \'b\'),               (3, \'c\'), (4, \'d\')]
+-- m2 =           [(1, "one"), (2, "two"),           (4, "three")]
 -- @
 --
 -- It will then pass the individual entries and pairs of entries
 -- to @g1@, @g2@, or @f@ as appropriate:
 --
 -- @
--- maybes = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]
+-- maybes = [g1 0 \'a\', f 1 \'b\' "one", g2 2 "two", g1 3 \'c\', f 4 \'d\' "three"]
 -- @
 --
 -- This produces a 'Maybe' for each key:
@@ -1915,7 +1915,7 @@ merge g1 g2 f m1 m2 =
 
 -- | An applicative version of 'merge'.
 --
--- @mergeA@ takes two 'WhenMissing' tactics, a 'WhenMatched'
+-- 'mergeA' takes two 'WhenMissing' tactics, a 'WhenMatched'
 -- tactic and two maps. It uses the tactics to merge the maps.
 -- Its behavior is best understood via its fundamental tactics,
 -- 'traverseMaybeMissing' and 'zipWithMaybeAMatched'.
@@ -1932,22 +1932,22 @@ merge g1 g2 f m1 m2 =
 -- Take, for example,
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'), (3,'c'), (4, 'd')]
+-- m1 = [(0, \'a\'), (1, \'b\'), (3,\'c\'), (4, \'d\')]
 -- m2 = [(1, "one"), (2, "two"), (4, "three")]
 -- @
 --
--- @mergeA@ will first ''align'' these maps by key:
+-- 'mergeA' will first \"align\" these maps by key:
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'),               (3,'c'), (4, 'd')]
--- m2 =           [(1, "one"), (2, "two"),          (4, "three")]
+-- m1 = [(0, \'a\'), (1, \'b\'),               (3, \'c\'), (4, \'d\')]
+-- m2 =           [(1, "one"), (2, "two"),           (4, "three")]
 -- @
 --
 -- It will then pass the individual entries and pairs of entries
 -- to @g1@, @g2@, or @f@ as appropriate:
 --
 -- @
--- actions = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]
+-- actions = [g1 0 \'a\', f 1 \'b\' "one", g2 2 "two", g1 3 \'c\', f 4 \'d\' "three"]
 -- @
 --
 -- Next, it will perform the actions in the @actions@ list in order from

Data/IntMap/Merge/Lazy.hs

@@ -39,8 +39,8 @@
 --
 -- == Efficiency note
 --
--- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
--- tactics are included because they are valid. However, they are
+-- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
+-- 'WhenMissing' tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 --

Data/IntMap/Merge/Strict.hs

@@ -39,8 +39,8 @@
 --
 -- == Efficiency note
 --
--- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
--- tactics are included because they are valid. However, they are
+-- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
+-- 'WhenMissing' tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 --

Data/IntMap/Strict.hs

@@ -22,7 +22,7 @@
 -- from key of type @Int@ to values of type @v@.
 --
 -- Each function in this module is careful to force values before installing
--- them in a 'Map'. This is usually more efficient when laziness is not
+-- them in an 'IntMap'. This is usually more efficient when laziness is not
 -- necessary. When laziness /is/ required, use the functions in
 -- "Data.IntMap.Lazy".
 --
@@ -60,9 +60,9 @@
 --
 -- The 'IntMap' type is shared between the lazy and strict modules, meaning that
 -- the same 'IntMap' value can be passed to functions in both modules. This
--- means that the 'Functor', 'Traversable' and 'Data' instances are the same as
--- for the "Data.IntMap.Lazy" module, so if they are used the resulting map may
--- contain suspended values (thunks).
+-- means that the 'Functor', 'Traversable' and 'Data.Data.Data' instances are
+-- the same as for the "Data.IntMap.Lazy" module, so if they are used the
+-- resulting map may contain suspended values (thunks).
 --
 --
 -- == Implementation

Data/Map.hs

@@ -101,7 +101,7 @@ insertLookupWithKey' :: Whoops "Data.Map.insertLookupWithKey' is gone. Use Data.
 insertLookupWithKey' _ _ _ _ = undefined
 
 -- | This function is being removed and is no longer usable.
--- Use 'foldr'.
+-- Use 'Data.Map.Strict.foldr'.
 fold :: Whoops "Data.Map.fold is gone. Use foldr."
      => (a -> b -> b) -> b -> Map k a -> b
 fold _ _ _ = undefined

Data/Map/Internal.hs

@@ -1202,8 +1202,8 @@ data AreWeStrict = Strict | Lazy
 -- a very large fraction of the time, you might consider using a
 -- private copy of the 'Identity' type.
 --
--- Note: 'alterF' is a flipped version of the 'at' combinator from
--- 'Control.Lens.At'.
+-- Note: 'alterF' is a flipped version of the @at@ combinator from
+-- @Control.Lens.At@.
 --
 -- @since 0.5.8
 alterF :: (Functor f, Ord k)
@@ -1990,7 +1990,7 @@ intersection t1@(Bin _ k x l1 r1) t2
 --
 -- @
 -- m \`restrictKeys\` s = 'filterWithKey' (\k _ -> k ``Set.member`` s) m
--- m \`restrictKeys\` s = m ``intersect`` 'fromSet' (const ()) s
+-- m \`restrictKeys\` s = m ``intersection`` 'fromSet' (const ()) s
 -- @
 --
 -- @since 0.5.8
@@ -2469,7 +2469,7 @@ traverseMaybeMissing f = WhenMissing
 
 -- | Merge two maps.
 --
--- @merge@ takes two 'WhenMissing' tactics, a 'WhenMatched'
+-- 'merge' takes two 'WhenMissing' tactics, a 'WhenMatched'
 -- tactic and two maps. It uses the tactics to merge the maps.
 -- Its behavior is best understood via its fundamental tactics,
 -- 'mapMaybeMissing' and 'zipWithMaybeMatched'.
@@ -2486,22 +2486,22 @@ traverseMaybeMissing f = WhenMissing
 -- Take, for example,
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'), (3,'c'), (4, 'd')]
+-- m1 = [(0, \'a\'), (1, \'b\'), (3, \'c\'), (4, \'d\')]
 -- m2 = [(1, "one"), (2, "two"), (4, "three")]
 -- @
 --
--- @merge@ will first ''align'' these maps by key:
+-- 'merge' will first \"align\" these maps by key:
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'),               (3,'c'), (4, 'd')]
--- m2 =           [(1, "one"), (2, "two"),          (4, "three")]
+-- m1 = [(0, \'a\'), (1, \'b\'),               (3, \'c\'), (4, \'d\')]
+-- m2 =           [(1, "one"), (2, "two"),           (4, "three")]
 -- @
 --
 -- It will then pass the individual entries and pairs of entries
 -- to @g1@, @g2@, or @f@ as appropriate:
 --
 -- @
--- maybes = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]
+-- maybes = [g1 0 \'a\', f 1 \'b\' "one", g2 2 "two", g1 3 \'c\', f 4 \'d\' "three"]
 -- @
 --
 -- This produces a 'Maybe' for each key:
@@ -2550,7 +2550,7 @@ merge g1 g2 f m1 m2 = runIdentity $
 
 -- | An applicative version of 'merge'.
 --
--- @mergeA@ takes two 'WhenMissing' tactics, a 'WhenMatched'
+-- 'mergeA' takes two 'WhenMissing' tactics, a 'WhenMatched'
 -- tactic and two maps. It uses the tactics to merge the maps.
 -- Its behavior is best understood via its fundamental tactics,
 -- 'traverseMaybeMissing' and 'zipWithMaybeAMatched'.
@@ -2567,22 +2567,22 @@ merge g1 g2 f m1 m2 = runIdentity $
 -- Take, for example,
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'), (3,'c'), (4, 'd')]
+-- m1 = [(0, \'a\'), (1, \'b\'), (3, \'c\'), (4, \'d\')]
 -- m2 = [(1, "one"), (2, "two"), (4, "three")]
 -- @
 --
--- @mergeA@ will first ''align'' these maps by key:
+-- @mergeA@ will first \"align\" these maps by key:
 --
 -- @
--- m1 = [(0, 'a'), (1, 'b'),               (3,'c'), (4, 'd')]
--- m2 =           [(1, "one"), (2, "two"),          (4, "three")]
+-- m1 = [(0, \'a\'), (1, \'b\'),               (3, \'c\'), (4, \'d\')]
+-- m2 =           [(1, "one"), (2, "two"),           (4, "three")]
 -- @
 --
 -- It will then pass the individual entries and pairs of entries
 -- to @g1@, @g2@, or @f@ as appropriate:
 --
 -- @
--- actions = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]
+-- actions = [g1 0 \'a\', f 1 \'b\' "one", g2 2 "two", g1 3 \'c\', f 4 \'d\' "three"]
 -- @
 --
 -- Next, it will perform the actions in the @actions@ list in order from

Data/Map/Lazy.hs

@@ -27,7 +27,7 @@
 --
 -- When deciding if this is the correct data structure to use, consider:
 --
--- * If you are using 'Int' keys, you will get much better performance for most
+-- * If you are using 'Prelude.Int' keys, you will get much better performance for most
 -- operations using "Data.IntMap.Lazy".
 --
 -- * If you don't care about ordering, consider using @Data.HashMap.Lazy@ from the
@@ -58,9 +58,9 @@
 --
 -- == Warning
 --
--- The size of a 'Map' must not exceed @maxBound::Int@. Violation of this
--- condition is not detected and if the size limit is exceeded, its behaviour is
--- undefined.
+-- The size of a 'Map' must not exceed @'Prelude.maxBound' :: 'Prelude.Int'@.
+-- Violation of this condition is not detected and if the size limit is exceeded,
+-- its behaviour is undefined.
 --
 --
 -- == Implementation

Data/Map/Merge/Lazy.hs

@@ -39,8 +39,8 @@
 --
 -- == Efficiency note
 --
--- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
--- tactics are included because they are valid. However, they are
+-- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
+-- 'WhenMissing' tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 --

Data/Map/Merge/Strict.hs

@@ -39,8 +39,8 @@
 --
 -- == Efficiency note
 --
--- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
--- tactics are included because they are valid. However, they are
+-- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
+-- 'WhenMissing' tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 --