Add clear warnings in Haddocks (#1087)

Add clear warnings for functions which have preconditions for creating valid structures.
haskell · Jan 19, 2025 · bb1ec48 · bb1ec48
1 parent 25036a9
commit bb1ec48
Show file tree

Hide file tree

Showing 6 changed files with 141 additions and 38 deletions.
diff --git a/containers/src/Data/IntMap/Internal.hs b/containers/src/Data/IntMap/Internal.hs
@@ -1358,7 +1358,7 @@ symDiffTip !t1 !k1 = go
 -- efficiency (with exception of 'union', 'difference' and 'intersection',
 -- where sharing of some nodes is lost with 'mergeWithKey').
 --
--- Please make sure you know what is going on when using 'mergeWithKey',
+-- __Warning__: Please make sure you know what is going on when using 'mergeWithKey',
 -- otherwise you can be surprised by unexpected code growth or even
 -- corruption of the data structure.
 --
@@ -2616,7 +2616,6 @@ mapKeysWith c f
 -- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
 -- is strictly monotonic.
 -- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
@@ -2626,6 +2625,10 @@ mapKeysWith c f
 -- This means that @f@ maps distinct original keys to distinct resulting keys.
 -- This function has slightly better performance than 'mapKeys'.
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'mapKeys' if the
+-- precondition may not hold.
+--
 -- > mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
 
 mapKeysMonotonic :: (Key->Key) -> IntMap a -> IntMap a
@@ -3336,6 +3339,10 @@ fromListWithKey f xs
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order.
 --
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
+--
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
 
@@ -3345,7 +3352,10 @@ fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x)
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -3357,7 +3367,10 @@ fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y)
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "5:b|a")]
@@ -3370,7 +3383,10 @@ fromAscListWithKey f = fromMonoListWithKey Nondistinct f
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order and all distinct.
--- /The precondition (input list is strictly ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 

diff --git a/containers/src/Data/IntMap/Strict/Internal.hs b/containers/src/Data/IntMap/Strict/Internal.hs
@@ -709,7 +709,7 @@ intersectionWithKey f m1 m2
 -- efficiency (with exception of 'union', 'difference' and 'intersection',
 -- where sharing of some nodes is lost with 'mergeWithKey').
 --
--- Please make sure you know what is going on when using 'mergeWithKey',
+-- __Warning__: Please make sure you know what is going on when using 'mergeWithKey',
 -- otherwise you can be surprised by unexpected code growth or even
 -- corruption of the data structure.
 --
@@ -1132,6 +1132,10 @@ fromListWithKey f xs
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order.
 --
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
+--
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
 
@@ -1141,7 +1145,10 @@ fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x)
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -1153,7 +1160,10 @@ fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y)
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -1165,7 +1175,10 @@ fromAscListWithKey f = fromMonoListWithKey Nondistinct f
 
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order and all distinct.
--- /The precondition (input list is strictly ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 

diff --git a/containers/src/Data/IntSet/Internal.hs b/containers/src/Data/IntSet/Internal.hs
@@ -1150,13 +1150,16 @@ map f = fromList . List.map f . toList
 -- | \(O(n)\). The
 --
 -- @'mapMonotonic' f s == 'map' f s@, but works only when @f@ is strictly increasing.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
 -- >                     ==> mapMonotonic f s == map f s
 -- >     where ls = toList s
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'map' if the
+-- precondition may not hold.
+--
 -- @since 0.6.3.1
 
 -- Note that for now the test is insufficient to support any fancier implementation.
@@ -1387,13 +1390,19 @@ fromRange (lx,rx)
     {-# INLINE shr1 #-}
 
 -- | \(O(n)\). Build a set from an ascending list of elements.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the elements are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 fromAscList :: [Key] -> IntSet
 fromAscList = fromMonoList
 {-# NOINLINE fromAscList #-}
 
 -- | \(O(n)\). Build a set from an ascending list of distinct elements.
--- /The precondition (input list is strictly ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the elements are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 fromDistinctAscList :: [Key] -> IntSet
 fromDistinctAscList = fromAscList
 {-# INLINE fromDistinctAscList #-}

diff --git a/containers/src/Data/Map/Internal.hs b/containers/src/Data/Map/Internal.hs
@@ -2784,7 +2784,7 @@ mergeA
 
 -- | \(O(n+m)\). An unsafe general combining function.
 --
--- WARNING: This function can produce corrupt maps and its results
+-- __Warning__: This function can produce corrupt maps and its results
 -- may depend on the internal structures of its inputs. Users should
 -- prefer 'merge' or 'mergeA'.
 --
@@ -3293,7 +3293,6 @@ mapKeysWith c f m =
 -- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
 -- is strictly monotonic.
 -- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
@@ -3303,6 +3302,10 @@ mapKeysWith c f m =
 -- This means that @f@ maps distinct original keys to distinct resulting keys.
 -- This function has better performance than 'mapKeys'.
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'mapKeys' if the
+-- precondition may not hold.
+--
 -- > mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
 -- > valid (mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")])) == True
 -- > valid (mapKeysMonotonic (\ _ -> 1)     (fromList [(5,"a"), (3,"b")])) == False
@@ -3663,7 +3666,10 @@ foldlFB = foldlWithKey
     fromAscListWith f xs == fromListWith f xs
 --------------------------------------------------------------------}
 -- | \(O(n)\). Build a map from an ascending list in linear time.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
@@ -3675,7 +3681,10 @@ fromAscList xs = fromAscListWithKey (\_ x _ -> x) xs
 {-# INLINE fromAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
 -- > fromDescList [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "b")]
@@ -3689,7 +3698,10 @@ fromDescList xs = fromDescListWithKey (\_ x _ -> x) xs
 {-# INLINE fromDescList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
@@ -3701,7 +3713,10 @@ fromAscListWith f xs
 {-# INLINE fromAscListWith #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
@@ -3718,7 +3733,10 @@ fromDescListWith f xs
 
 -- | \(O(n)\). Build a map from an ascending list in linear time with a
 -- combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -3740,7 +3758,10 @@ fromAscListWithKey f xs = ascLinkAll (Foldable.foldl' next Nada xs)
 
 -- | \(O(n)\). Build a map from a descending list in linear time with a
 -- combining function for equal keys.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -3762,7 +3783,10 @@ fromDescListWithKey f xs = descLinkAll (Foldable.foldl' next Nada xs)
 
 
 -- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
@@ -3789,7 +3813,10 @@ ascLinkAll stk = foldl'Stack (\r kx x l -> link kx x l r) Tip stk
 {-# INLINABLE ascLinkAll #-}
 
 -- | \(O(n)\). Build a map from a descending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly decreasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True

diff --git a/containers/src/Data/Map/Strict/Internal.hs b/containers/src/Data/Map/Strict/Internal.hs
@@ -1199,7 +1199,7 @@ forceMaybe m@(Just !_) = m
 
 -- | \(O(n+m)\). An unsafe universal combining function.
 --
--- WARNING: This function can produce corrupt maps and its results
+-- __Warning__: This function can produce corrupt maps and its results
 -- may depend on the internal structures of its inputs. Users should
 -- prefer 'Data.Map.Merge.Strict.merge' or
 -- 'Data.Map.Merge.Strict.mergeA'.
@@ -1570,7 +1570,10 @@ fromListWithKey f xs =
 --------------------------------------------------------------------}
 
 -- | \(O(n)\). Build a map from an ascending list in linear time.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
@@ -1582,7 +1585,10 @@ fromAscList xs
 {-# INLINE fromAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
 -- > fromDescList [(5,"a"), (5,"b"), (3,"a")] == fromList [(3, "b"), (5, "b")]
@@ -1594,7 +1600,10 @@ fromDescList xs
 {-# INLINE fromDescList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
@@ -1608,7 +1617,10 @@ fromAscListWith f xs
 {-# INLINE fromAscListWith #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
@@ -1623,7 +1635,10 @@ fromDescListWith f xs
 
 -- | \(O(n)\). Build a map from an ascending list in linear time with a
 -- combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -1646,7 +1661,10 @@ fromAscListWithKey f xs = ascLinkAll (Foldable.foldl' next Nada xs)
 
 -- | \(O(n)\). Build a map from a descending list in linear time with a
 -- combining function for equal keys.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -1668,7 +1686,10 @@ fromDescListWithKey f xs = descLinkAll (Foldable.foldl' next Nada xs)
 {-# INLINE fromDescListWithKey #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
@@ -1684,7 +1705,10 @@ fromDistinctAscList xs = ascLinkAll (Foldable.foldl' next Nada xs)
 {-# INLINE fromDistinctAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly decreasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True