[commit: packages/containers] cleaned_bugfix394, master, merge-doc-target, merge-fixes-5.9, merge-restrict-fix-5.8, revert-408-bugfix_394: Deprecate some functions in Data.Map (989017b)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/containers

On branches: cleaned_bugfix394,master,merge-doc-target,merge-fixes-5.9,merge-restrict-fix-5.8,revert-408-bugfix_394
Link       : http://git.haskell.org/packages/containers.git/commitdiff/989017b5029b886c36ead0addad8773b8ff4bed2

>---------------------------------------------------------------

commit 989017b5029b886c36ead0addad8773b8ff4bed2
Author: David Feuer <David.Feuer at gmail.com>
Date:   Tue Aug 30 23:13:18 2016 -0400

    Deprecate some functions in Data.Map
    
    * `Data.Map` has had several functions documented as deprecated,
    but without actual `DEPRECATED` pragmas, for years. Add the
    pragmas so we can move toward removal in a couple more major
    versions.
    
    * The `showTree` and `showTreeWith` functions don't seem like a
    good fit for the public API. I'm deprecating them, but they will
    remain available for the foreseeable future in `Data.Map.Base`
    or some other internal module.


>---------------------------------------------------------------

989017b5029b886c36ead0addad8773b8ff4bed2
 Data/Map.hs      | 30 ++++++++++--------------------
 Data/Map/Base.hs |  2 ++
 changelog.md     | 10 ++++++++++
 3 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/Data/Map.hs b/Data/Map.hs
index ec0326f..dfb0797 100644
--- a/Data/Map.hs
+++ b/Data/Map.hs
@@ -72,16 +72,14 @@ import Prelude hiding (foldr)
 import Data.Map.Lazy
 import qualified Data.Map.Strict as Strict
 
--- | /Deprecated./ As of version 0.5, replaced by 'Data.Map.Strict.insertWith'.
---
--- /O(log n)/. Same as 'insertWith', but the value being inserted to the map is
+-- | /O(log n)/. Same as 'insertWith', but the value being inserted to the map is
 -- evaluated to WHNF beforehand.
 --
 -- For example, to update a counter:
 --
 -- > insertWith' (+) k 1 m
 --
-
+{-# DEPRECATED insertWith' "As of version 0.5, replaced by 'Data.Map.Strict.insertWith'." #-}
 insertWith' :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a
 insertWith' = Strict.insertWith
 #if __GLASGOW_HASKELL__
@@ -90,12 +88,9 @@ insertWith' = Strict.insertWith
 {-# INLINE insertWith' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by
--- 'Data.Map.Strict.insertWithKey'.
---
--- /O(log n)/. Same as 'insertWithKey', but the value being inserted to the map is
+-- | /O(log n)/. Same as 'insertWithKey', but the value being inserted to the map is
 -- evaluated to WHNF beforehand.
-
+{-# DEPRECATED insertWithKey' "As of version 0.5, replaced by 'Data.Map.Strict.insertWithKey'." #-}
 insertWithKey' :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a
 -- We do not reuse Data.Map.Strict.insertWithKey, because it is stricter -- it
 -- forces evaluation of the given value.
@@ -106,12 +101,9 @@ insertWithKey' = Strict.insertWithKey
 {-# INLINE insertWithKey' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by
--- 'Data.Map.Strict.insertLookupWithKey'.
---
--- /O(log n)/. Same as 'insertLookupWithKey', but the value being inserted to
+-- | /O(log n)/. Same as 'insertLookupWithKey', but the value being inserted to
 -- the map is evaluated to WHNF beforehand.
-
+{-# DEPRECATED insertLookupWithKey' "As of version 0.5, replaced by 'Data.Map.Strict.insertLookupWithKey'." #-}
 insertLookupWithKey' :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a
                      -> (Maybe a, Map k a)
 -- We do not reuse Data.Map.Strict.insertLookupWithKey, because it is stricter -- it
@@ -123,20 +115,18 @@ insertLookupWithKey' = Strict.insertLookupWithKey
 {-# INLINE insertLookupWithKey' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by 'foldr'.
---
--- /O(n)/. Fold the values in the map using the given right-associative
+-- | /O(n)/. Fold the values in the map using the given right-associative
 -- binary operator. This function is an equivalent of 'foldr' and is present
 -- for compatibility only.
+{-# DEPRECATED fold "As of version 0.5, replaced by 'foldr'." #-}
 fold :: (a -> b -> b) -> b -> Map k a -> b
 fold = foldr
 {-# INLINE fold #-}
 
--- | /Deprecated./ As of version 0.4, replaced by 'foldrWithKey'.
---
--- /O(n)/. Fold the keys and values in the map using the given right-associative
+-- | /O(n)/. Fold the keys and values in the map using the given right-associative
 -- binary operator. This function is an equivalent of 'foldrWithKey' and is present
 -- for compatibility only.
+{-# DEPRECATED foldWithKey "As of version 0.4, replaced by 'foldrWithKey'." #-}
 foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b
 foldWithKey = foldrWithKey
 {-# INLINE foldWithKey #-}
diff --git a/Data/Map/Base.hs b/Data/Map/Base.hs
index 9ebae06..c31a576 100644
--- a/Data/Map/Base.hs
+++ b/Data/Map/Base.hs
@@ -3965,6 +3965,7 @@ instance (Show k, Show a) => Show (Map k a) where
 
 -- | /O(n)/. Show the tree that implements the map. The tree is shown
 -- in a compressed, hanging format. See 'showTreeWith'.
+{-# DEPRECATED showTree "This function is being removed from the public API." #-}
 showTree :: (Show k,Show a) => Map k a -> String
 showTree m
   = showTreeWith showElem True False m
@@ -4008,6 +4009,7 @@ showTree m
 >     +--(1,())
 
 -}
+{-# DEPRECATED showTreeWith "This function is being removed from the public API." #-}
 showTreeWith :: (k -> a -> String) -> Bool -> Bool -> Map k a -> String
 showTreeWith showelem hang wide t
   | hang      = (showsTreeHang showelem wide [] t) ""
diff --git a/changelog.md b/changelog.md
index 8abdb54..d180353 100644
--- a/changelog.md
+++ b/changelog.md
@@ -64,6 +64,16 @@
 
   * Make `drawTree` handle newlines better. (Thanks, recursion-ninja!)
 
+### Deprecations
+
+  * All functions in `Data.Map` proper that have been documented as deprecated since
+    version 0.5 or before now have `DEPRECATED` pragmas and will actually be
+    removed after another cycle or two.
+
+  * Tree printing functions in `Data.Map` intended for library debugging are now
+    deprecated. They will continue to be available for the foreseeable future in
+    an internal module.
+
 ### Performance changes
 
   * Substantially speed up `splitAt`, `zipWith`, `take`, `drop`,