Minor documentation changes

Author: fpringle

generic-diff-instances/src/Generics/Diff/Special/Map.hs

@@ -30,7 +30,7 @@ data MapDiffError k v
   deriving (Show, Eq)
 
 {- | Render a 'MapDiffError'. This is a top-level function because we'll use it in the implementations
-of 'renderSpecialDiffError' for both 'Map' and 'IntMap'.
+of 'renderSpecialDiffError' for both 'Map' and 'Data.IntMap.IntMap'.
 -}
 mapDiffErrorDoc :: (Show k) => MapDiffError k v -> Doc
 mapDiffErrorDoc = \case
@@ -43,9 +43,6 @@ mapDiffErrorDoc = \case
   RightMissingKey k ->
     linesDoc $ pure $ "The left map contains key " <> showB k <> " but the right doesn't"
 
-------------------------------------------------------------
--- Map
-
 instance (Show k, Ord k, Diff v) => SpecialDiff (Map k v) where
   type SpecialDiffError (Map k v) = MapDiffError k v
 
@@ -67,6 +64,5 @@ instance (Show k, Ord k, Diff v) => SpecialDiff (Map k v) where
 
   renderSpecialDiffError = mapDiffErrorDoc
 
--- | Now we can implement 'Diff' using 'diffWithSpecial'.
 instance (Show k, Ord k, Diff v) => Diff (Map k v) where
   diff = diffWithSpecial

generic-diff-instances/src/Generics/Diff/Special/Set.hs

@@ -31,7 +31,7 @@ data SetDiffError k
   deriving (Show, Eq)
 
 {- | Render a 'SetDiffError'. This is a top-level function because we'll use it in the implementations
-of 'renderSpecialDiffError' for both 'Set' and 'IntSet'.
+of 'renderSpecialDiffError' for both 'Set' and 'Data.IntSet.IntSet'.
 
 There are no nested 'DiffError's here, so we use 'linesDoc'.
 -}
@@ -42,9 +42,8 @@ setDiffErrorDoc = \case
   RightMissingKey k ->
     linesDoc $ pure $ "The left set contains key " <> showB k <> " but the right doesn't"
 
-{- | First we define an instance of 'SpecialDiff'. We need 'Show' and 'Eq' so that 'SetDiffError'
-also has these instances; we need 'Ord' to compare elements of the set.
--}
+-- First we define an instance of 'SpecialDiff'. We need 'Show' and 'Eq' so that 'SetDiffError'
+-- also has these instances; we need 'Ord' to compare elements of the set.
 instance (Show k, Eq k, Ord k) => SpecialDiff (Set k) where
   type SpecialDiffError (Set k) = SetDiffError k
 
@@ -62,6 +61,6 @@ instance (Show k, Eq k, Ord k) => SpecialDiff (Set k) where
 
   renderSpecialDiffError = setDiffErrorDoc
 
--- | Now we can implement 'Diff' using 'diffWithSpecial'.
+-- Now we can implement 'Diff' using 'diffWithSpecial'.
 instance (Show k, Ord k) => Diff (Set k) where
   diff = diffWithSpecial

generic-diff-instances/src/Generics/Diff/Special/Tree.hs

@@ -1,7 +1,7 @@
 {-# LANGUAGE DerivingVia #-}
 {-# OPTIONS_GHC -Wno-orphans #-}
 
-{- | A worked example of implementing 'SpecialDiff' (and thereby 'Diff') for 'Tree's.
+{- | A worked example of implementing 'SpecialDiff' (and thereby 'Diff') for 'Tree.Tree's.
 
 As with other 3rd-party types, there are different approaches we can take here. We'll show 2 of them:
 
@@ -22,6 +22,7 @@ import Generics.SOP.GGP
 ------------------------------------------------------------
 -- Using gspecialDiffNested
 
+-- | Generically-derived instance.
 instance (Diff a) => SpecialDiff (Tree.Tree a) where
   type SpecialDiffError (Tree.Tree a) = DiffErrorNested (GCode (Tree.Tree a))
   specialDiff = gspecialDiffNested
@@ -33,17 +34,23 @@ instance (Diff a) => Diff (Tree.Tree a) where
 ------------------------------------------------------------
 -- Using SpecialDiff
 
+{- | A newtype wrapper around 'Tree.Tree' to demonstrate one alternate way we could hand-write
+a 'SpecialDiff' instance.
+-}
 newtype CustomTree a = CustomTree (Tree.Tree a)
   deriving (Show) via (Tree.Tree a)
 
+-- | Where are we in the tree? Each element of the list says which child node we step to next.
 newtype TreePath = TreePath [Int]
   deriving (Show, Eq) via [Int]
 
+-- | A custom error type for 'CustomTree'.
 data CustomTreeDiffError a
   = DiffAtNode TreePath (DiffError a)
   | WrongLengthsOfChildren TreePath Int Int
   deriving (Show, Eq)
 
+-- | Render a tree path as a 'TB.Builder'
 renderTreePath :: TreePath -> TB.Builder
 renderTreePath (TreePath []) = "<root>"
 renderTreePath (TreePath (x : xs)) = mconcat $ showB x : ["->" <> showB y | y <- xs]