Improve Haddocks for partial functions (#1140)

Document partial functions in a consistent manner.
Specify the error condition and mention total alternatives, if any.

Author: meooow25

containers/src/Data/IntMap/Internal.hs

@@ -416,6 +416,8 @@ deriving instance Lift a => Lift (IntMap a)
 -- | \(O(\min(n,W))\). Find the value at a key.
 -- Calls 'error' when the element can not be found.
 --
+-- __Note__: This function is partial. Prefer '!?'.
+--
 -- > fromList [(5,'a'), (3,'b')] ! 1    Error: element not in the map
 -- > fromList [(5,'a'), (3,'b')] ! 5 == 'a'
 
@@ -2328,14 +2330,18 @@ minView :: IntMap a -> Maybe (a, IntMap a)
 minView t = fmap (\((_, x), t') -> (x, t')) (minViewWithKey t)
 
 -- | \(O(\min(n,W))\). Delete and find the maximal element.
--- This function throws an error if the map is empty. Use 'maxViewWithKey'
--- if the map may be empty.
+--
+-- Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'maxViewWithKey'.
 deleteFindMax :: IntMap a -> ((Key, a), IntMap a)
 deleteFindMax = fromMaybe (error "deleteFindMax: empty map has no maximal element") . maxViewWithKey
 
 -- | \(O(\min(n,W))\). Delete and find the minimal element.
--- This function throws an error if the map is empty. Use 'minViewWithKey'
--- if the map may be empty.
+--
+-- Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'minViewWithKey'.
 deleteFindMin :: IntMap a -> ((Key, a), IntMap a)
 deleteFindMin = fromMaybe (error "deleteFindMin: empty map has no minimal element") . minViewWithKey
 
@@ -2369,6 +2375,8 @@ lookupMin (Bin p l r) =
 {-# INLINE lookupMin #-} -- See Note [Inline lookupMin] in Data.Set.Internal
 
 -- | \(O(\min(n,W))\). The minimal key of the map. Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'lookupMin'.
 findMin :: IntMap a -> (Key, a)
 findMin t
   | Just r <- lookupMin t = r
@@ -2388,6 +2396,8 @@ lookupMax (Bin p l r) =
 {-# INLINE lookupMax #-} -- See Note [Inline lookupMin] in Data.Set.Internal
 
 -- | \(O(\min(n,W))\). The maximal key of the map. Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'lookupMax'.
 findMax :: IntMap a -> (Key, a)
 findMax t
   | Just r <- lookupMax t = r

containers/src/Data/IntMap/Lazy.hs

@@ -249,12 +249,8 @@ module Data.IntMap.Lazy (
     -- * Min\/Max
     , lookupMin
     , lookupMax
-    , findMin
-    , findMax
     , deleteMin
     , deleteMax
-    , deleteFindMin
-    , deleteFindMax
     , updateMin
     , updateMax
     , updateMinWithKey
@@ -263,6 +259,10 @@ module Data.IntMap.Lazy (
     , maxView
     , minViewWithKey
     , maxViewWithKey
+    , findMin
+    , findMax
+    , deleteFindMin
+    , deleteFindMax
     ) where
 
 import Data.IntMap.Internal as IM

containers/src/Data/IntMap/Strict.hs

@@ -267,12 +267,8 @@ module Data.IntMap.Strict (
     -- * Min\/Max
     , lookupMin
     , lookupMax
-    , findMin
-    , findMax
     , deleteMin
     , deleteMax
-    , deleteFindMin
-    , deleteFindMax
     , updateMin
     , updateMax
     , updateMinWithKey
@@ -281,6 +277,10 @@ module Data.IntMap.Strict (
     , maxView
     , minViewWithKey
     , maxViewWithKey
+    , findMin
+    , findMax
+    , deleteFindMin
+    , deleteFindMax
     ) where
 
 import Data.IntMap.Strict.Internal

containers/src/Data/IntSet.hs

@@ -166,14 +166,14 @@ module Data.IntSet (
             -- * Min\/Max
             , lookupMin
             , lookupMax
-            , findMin
-            , findMax
             , deleteMin
             , deleteMax
-            , deleteFindMin
-            , deleteFindMax
             , maxView
             , minView
+            , findMin
+            , findMax
+            , deleteFindMin
+            , deleteFindMax
 
             -- * Conversion
 

containers/src/Data/IntSet/Internal.hs

@@ -1103,13 +1103,17 @@ minView t =
 
 -- | \(O(\min(n,W))\). Delete and find the minimal element.
 --
--- > deleteFindMin set = (findMin set, deleteMin set)
+-- Calls 'error' if the set is empty.
+--
+-- __Note__: This function is partial. Prefer 'minView'.
 deleteFindMin :: IntSet -> (Key, IntSet)
 deleteFindMin = fromMaybe (error "deleteFindMin: empty set has no minimal element") . minView
 
 -- | \(O(\min(n,W))\). Delete and find the maximal element.
 --
--- > deleteFindMax set = (findMax set, deleteMax set)
+-- Calls 'error' if the set is empty.
+--
+-- __Note__: This function is partial. Prefer 'maxView'.
 deleteFindMax :: IntSet -> (Key, IntSet)
 deleteFindMax = fromMaybe (error "deleteFindMax: empty set has no maximal element") . maxView
 
@@ -1130,6 +1134,8 @@ lookupMin (Bin p l r) = Just $! lookupMinSure (if signBranch p then r else l)
 
 -- | \(O(\min(n,W))\). The minimal element of the set. Calls 'error' if the set
 -- is empty.
+--
+-- __Note__: This function is partial. Prefer 'lookupMin'.
 findMin :: IntSet -> Key
 findMin t
   | Just r <- lookupMin t = r
@@ -1152,6 +1158,8 @@ lookupMax (Bin p l r) = Just $! lookupMaxSure (if signBranch p then l else r)
 
 -- | \(O(\min(n,W))\). The maximal element of the set. Calls 'error' if the set
 -- is empty.
+--
+-- __Note__: This function is partial. Prefer 'lookupMax'.
 findMax :: IntSet -> Key
 findMax t
   | Just r <- lookupMax t = r

containers/src/Data/Map/Internal.hs

@@ -434,6 +434,8 @@ infixl 9 !,!?,\\ --
 -- | \(O(\log n)\). Find the value at a key.
 -- Calls 'error' when the element can not be found.
 --
+-- __Note__: This function is partial. Prefer '!?'.
+--
 -- > fromList [(5,'a'), (3,'b')] ! 1    Error: element not in the map
 -- > fromList [(5,'a'), (3,'b')] ! 5 == 'a'
 
@@ -623,8 +625,6 @@ notMember k m = not $ member k m
 {-# INLINE notMember #-}
 #endif
 
--- | \(O(\log n)\). Find the value at a key.
--- Calls 'error' when the element can not be found.
 find :: Ord k => k -> Map k a -> a
 find = go
   where
@@ -1456,6 +1456,8 @@ alterFYoneda = go
 -- including, the 'size' of the map. Calls 'error' when the key is not
 -- a 'member' of the map.
 --
+-- __Note__: This function is partial. Prefer 'lookupIndex'.
+--
 -- > findIndex 2 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map
 -- > findIndex 3 (fromList [(5,"a"), (3,"b")]) == 0
 -- > findIndex 5 (fromList [(5,"a"), (3,"b")]) == 1
@@ -1502,6 +1504,8 @@ lookupIndex = go 0
 -- index in the sequence sorted by keys. If the /index/ is out of range (less
 -- than zero, greater or equal to 'size' of the map), 'error' is called.
 --
+-- __Note__: This function is partial.
+--
 -- > elemAt 0 (fromList [(5,"a"), (3,"b")]) == (3,"b")
 -- > elemAt 1 (fromList [(5,"a"), (3,"b")]) == (5, "a")
 -- > elemAt 2 (fromList [(5,"a"), (3,"b")])    Error: index out of range
@@ -1586,6 +1590,8 @@ splitAt i0 m0
 -- the sequence sorted by keys. If the /index/ is out of range (less than zero,
 -- greater or equal to 'size' of the map), 'error' is called.
 --
+-- __Note__: This function is partial.
+--
 -- > updateAt (\ _ _ -> Just "x") 0    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")]
 -- > updateAt (\ _ _ -> Just "x") 1    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "x")]
 -- > updateAt (\ _ _ -> Just "x") 2    (fromList [(5,"a"), (3,"b")])    Error: index out of range
@@ -1612,6 +1618,8 @@ updateAt f !i t =
 -- the sequence sorted by keys. If the /index/ is out of range (less than zero,
 -- greater or equal to 'size' of the map), 'error' is called.
 --
+-- __Note__: This function is partial.
+--
 -- > deleteAt 0  (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
 -- > deleteAt 1  (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
 -- > deleteAt 2 (fromList [(5,"a"), (3,"b")])     Error: index out of range
@@ -1669,6 +1677,8 @@ lookupMin (Bin _ k x l _) = Just $! kvToTuple (lookupMinSure k x l)
 
 -- | \(O(\log n)\). The minimal key of the map. Calls 'error' if the map is empty.
 --
+-- __Note__: This function is partial. Prefer 'lookupMin'.
+--
 -- > findMin (fromList [(5,"a"), (3,"b")]) == (3,"b")
 -- > findMin empty                            Error: empty map has no minimal element
 
@@ -1695,6 +1705,8 @@ lookupMax (Bin _ k x _ r) = Just $! kvToTuple (lookupMaxSure k x r)
 
 -- | \(O(\log n)\). The maximal key of the map. Calls 'error' if the map is empty.
 --
+-- __Note__: This function is partial. Prefer 'lookupMax'.
+--
 -- > findMax (fromList [(5,"a"), (3,"b")]) == (5,"a")
 -- > findMax empty                            Error: empty map has no maximal element
 
@@ -4107,19 +4119,19 @@ maxViewSure !k x !l r = case r of
 
 -- | \(O(\log n)\). Delete and find the minimal element.
 --
--- > deleteFindMin (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((3,"b"), fromList[(5,"a"), (10,"c")])
--- > deleteFindMin empty                                      Error: can not return the minimal element of an empty map
-
+-- Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'minViewWithKey'.
 deleteFindMin :: Map k a -> ((k,a),Map k a)
 deleteFindMin t = case minViewWithKey t of
   Nothing -> (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip)
   Just res -> res
 
 -- | \(O(\log n)\). Delete and find the maximal element.
 --
--- > deleteFindMax (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((10,"c"), fromList [(3,"b"), (5,"a")])
--- > deleteFindMax empty                                      Error: can not return the maximal element of an empty map
-
+-- Calls 'error' if the map is empty.
+--
+-- __Note__: This function is partial. Prefer 'maxViewWithKey'.
 deleteFindMax :: Map k a -> ((k,a),Map k a)
 deleteFindMax t = case maxViewWithKey t of
   Nothing -> (error "Map.deleteFindMax: can not return the maximal element of an empty map", Tip)

containers/src/Data/Map/Lazy.hs

@@ -272,12 +272,8 @@ module Data.Map.Lazy (
     -- * Min\/Max
     , lookupMin
     , lookupMax
-    , findMin
-    , findMax
     , deleteMin
     , deleteMax
-    , deleteFindMin
-    , deleteFindMax
     , updateMin
     , updateMax
     , updateMinWithKey
@@ -286,6 +282,10 @@ module Data.Map.Lazy (
     , maxView
     , minViewWithKey
     , maxViewWithKey
+    , findMin
+    , findMax
+    , deleteFindMin
+    , deleteFindMax
 
     -- * Debugging
     , valid

containers/src/Data/Map/Strict.hs

@@ -287,12 +287,8 @@ module Data.Map.Strict
     -- * Min\/Max
     , lookupMin
     , lookupMax
-    , findMin
-    , findMax
     , deleteMin
     , deleteMax
-    , deleteFindMin
-    , deleteFindMax
     , updateMin
     , updateMax
     , updateMinWithKey
@@ -301,6 +297,10 @@ module Data.Map.Strict
     , maxView
     , minViewWithKey
     , maxViewWithKey
+    , findMin
+    , findMax
+    , deleteFindMin
+    , deleteFindMax
 
     -- * Debugging
     , valid

containers/src/Data/Map/Strict/Internal.hs

@@ -838,6 +838,8 @@ atKeyIdentity k f t = Identity $ atKeyPlain Strict k (coerce f) t
 -- | \(O(\log n)\). Update the element at /index/. Calls 'error' when an
 -- invalid index is used.
 --
+-- __Note__: This function is partial.
+--
 -- > updateAt (\ _ _ -> Just "x") 0    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")]
 -- > updateAt (\ _ _ -> Just "x") 1    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "x")]
 -- > updateAt (\ _ _ -> Just "x") 2    (fromList [(5,"a"), (3,"b")])    Error: index out of range