Haddock fixes (#560)

harpocrates · m-renaud · commit 6b070fcb01ec · 2018-12-01T22:27:21.000-08:00
Tweaked documentation fixing Haddock markup. Mostly:

  * qualifying out-of-scope or ambiguous identifiers
  * properly escaping character literals in examples
  * several obvious typos
diff --git a/Data/Graph.hs b/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'])]
diff --git a/Data/IntMap/Internal.hs b/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
diff --git a/Data/IntMap/Merge/Lazy.hs b/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.
 --
diff --git a/Data/IntMap/Merge/Strict.hs b/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.
 --
diff --git a/Data/IntMap/Strict.hs b/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
diff --git a/Data/Map.hs b/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
diff --git a/Data/Map/Internal.hs b/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
diff --git a/Data/Map/Lazy.hs b/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
diff --git a/Data/Map/Merge/Lazy.hs b/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.
 --
diff --git a/Data/Map/Merge/Strict.hs b/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.
 --
diff --git a/Data/Map/Strict.hs b/Data/Map/Strict.hs
@@ -33,8 +33,8 @@
 --
 -- 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
--- operations using "Data.IntMap.Strict".
+-- * If you are using 'Prelude.Int' keys, you will get much better performance for
+-- most operations using "Data.IntMap.Strict".
 --
 -- * If you don't care about ordering, consider use @Data.HashMap.Strict@ from the
 -- <https://hackage.haskell.org/package/unordered-containers unordered-containers>
@@ -70,9 +70,9 @@
 --
 -- The 'Map' type is shared between the lazy and strict modules, meaning that
 -- the same 'Map' 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.Map.Lazy" module, so if they are used the resulting maps may contain
--- suspended values (thunks).
+-- that the 'Data.Functor.Functor', 'Data.Traversable.Traversable' and
+-- 'Data.Data.Data' instances are the same as for the "Data.Map.Lazy" module, so
+-- if they are used the resulting maps may contain suspended values (thunks).
 --
 --
 -- == Implementation
diff --git a/Data/Map/Strict/Internal.hs b/Data/Map/Strict/Internal.hs
@@ -72,7 +72,7 @@
 -- Operation comments contain the operation time complexity in
 -- the Big-O notation (<http://en.wikipedia.org/wiki/Big_O_notation>).
 --
--- Be aware that the 'Functor', 'Traversable' and 'Data' instances
+-- Be aware that the 'Functor', 'Traversable' and 'Data.Data.Data' instances
 -- are the same as for the "Data.Map.Lazy" module, so if they are used
 -- on strict maps, the resulting maps will be lazy.
 -----------------------------------------------------------------------------
@@ -843,8 +843,8 @@ alter = go
 -- 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@.
 alterF :: (Functor f, Ord k)
        => (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)
 alterF f k m = atKeyImpl Strict k f m
diff --git a/Data/Sequence.hs b/Data/Sequence.hs
@@ -91,7 +91,7 @@
 -- * The 'Functor' methods 'fmap' and '<$', along with 'mapWithIndex'
 -- * The 'Applicative' methods '<*>', '*>', and '<*'
 -- * The zips: 'zipWith', 'zip', etc.
--- * 'heads' and 'tails'
+-- * 'inits', 'tails'
 -- * 'fromFunction', 'replicate', 'intersperse', and 'cycleTaking'
 -- * 'reverse'
 -- * 'chunksOf'
@@ -156,7 +156,7 @@ module Data.Sequence (
     unfoldl,        -- :: (b -> Maybe (b, a)) -> b -> Seq a
     -- * Deconstruction
     -- | Additional functions for deconstructing sequences are available
-    -- via the 'Foldable' instance of 'Seq'.
+    -- via the 'Data.Foldable.Foldable' instance of 'Seq'.
 
     -- ** Queries
     null,           -- :: Seq a -> Bool
@@ -218,7 +218,8 @@ module Data.Sequence (
     findIndexR,     -- :: (a -> Bool) -> Seq a -> Maybe Int
     findIndicesR,   -- :: (a -> Bool) -> Seq a -> [Int]
     -- * Folds
-    -- | General folds are available via the 'Foldable' instance of 'Seq'.
+    -- | General folds are available via the 'Data.Foldable.Foldable' instance
+    -- of 'Seq'.
     foldMapWithIndex, -- :: Monoid m => (Int -> a -> m) -> Seq a -> m
     foldlWithIndex, -- :: (b -> Int -> a -> b) -> b -> Seq a -> b
     foldrWithIndex, -- :: (Int -> a -> b -> b) -> b -> Seq a -> b
diff --git a/Data/Sequence/Internal.hs b/Data/Sequence/Internal.hs
@@ -645,10 +645,10 @@ type Digit23 a = Node a
 -- gets to the bottom, it turns the tree into a 2-3 tree, applies 'mapMulFT' to
 -- produce the main body, and glues all the pieces together.
 --
--- 'map23' itself is a bit horrifying because of the nested types involved. Its
+-- @map23@ itself is a bit horrifying because of the nested types involved. Its
 -- job is to map over the *elements* of a 2-3 tree, rather than the subtrees.
 -- If we used a higher-order nested type with MPTC, we could probably use a
--- class, but as it is we have to build up 'map23' explicitly through the
+-- class, but as it is we have to build up @map23@ explicitly through the
 -- recursion.
 aptyMiddle
   :: (b -> c)
diff --git a/Data/Sequence/Internal/Sorting.hs b/Data/Sequence/Internal/Sorting.hs
@@ -396,7 +396,7 @@ foldToMaybeTree (<+>) f (Deep _ pr m sf) =
     m' = foldToMaybeTree (<+>) (foldNode (<+>) f) m
 {-# INLINE foldToMaybeTree #-}
 
--- | A 'foldMapWithIndex'-like function, specialized to the
+-- | A 'Data.Sequence.foldMapWithIndex'-like function, specialized to the
 -- 'Data.Semigroup.Option' monoid, which takes advantage of the
 -- internal structure of 'Seq' to avoid wrapping in 'Maybe' at certain
 -- points.
diff --git a/Data/Set/Internal.hs b/Data/Set/Internal.hs
@@ -1721,8 +1721,8 @@ powerSet xs0 = insertMin empty (foldr' step Tip xs0) where
 -- Example:
 --
 -- @
--- cartesianProduct (fromList [1,2]) (fromList ['a','b']) =
---   fromList [(1,'a'), (1,'b'), (2,'a'), (2,'b')]
+-- cartesianProduct (fromList [1,2]) (fromList [\'a\',\'b\']) =
+--   fromList [(1,\'a\'), (1,\'b\'), (2,\'a\'), (2,\'b\')]
 -- @
 --
 -- @since 0.5.11
