[commit: containers] master: More documentation tweaks (c09607e)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/containers

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/c09607e85954cef5dd4b1c411c321ed4799d527a

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

commit c09607e85954cef5dd4b1c411c321ed4799d527a
Author: Johan Tibell <johan.tibell at gmail.com>
Date:   Thu Nov 17 22:27:42 2011 -0800

    More documentation tweaks

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

 Data/Map.hs        |   28 +++-------------------------
 Data/Map/Lazy.hs   |   11 +++++++----
 Data/Map/Strict.hs |   17 ++++++++++-------
 3 files changed, 20 insertions(+), 36 deletions(-)

diff --git a/Data/Map.hs b/Data/Map.hs
index 2af597a..fbc8372 100644
--- a/Data/Map.hs
+++ b/Data/Map.hs
@@ -12,31 +12,9 @@
 -- Stability   :  provisional
 -- Portability :  portable
 --
--- An efficient implementation of maps from keys to values (dictionaries).

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

--- Since many function names (but not the type name) clash with
--- "Prelude" names, this module is usually imported @qualified@, e.g.

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

--- >  import Data.Map (Map)
--- >  import qualified Data.Map as Map

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

--- The implementation of 'Map' is based on /size balanced/ binary trees (or
--- trees of /bounded balance/) as described by:

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

---    * Stephen Adams, \"/Efficient sets: a balancing act/\",
---     Journal of Functional Programming 3(4):553-562, October 1993,
---     <http://www.swiss.ai.mit.edu/~adams/BB/>.

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

---    * J. Nievergelt and E.M. Reingold,
---      \"/Binary search trees of bounded balance/\",
---      SIAM journal of computing 2(1), March 1973.

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

--- Note that the implementation is /left-biased/ -- the elements of a
--- first argument are always preferred to the second, for example in
--- 'union' or 'insert'.

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

--- Operation comments contain the operation time complexity in
--- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
+-- /Deprecated./ As of version 0.5, replaced by 'Data.Map.Lazy' and
+-- 'Data.Map.Strict'. These two modules implement value lazy and value
+-- strict maps, respectively.
 -----------------------------------------------------------------------------
 
 module Data.Map
diff --git a/Data/Map/Lazy.hs b/Data/Map/Lazy.hs
index cf94159..3828767 100644
--- a/Data/Map/Lazy.hs
+++ b/Data/Map/Lazy.hs
@@ -15,10 +15,13 @@
 -- An efficient implementation of ordered maps from keys to values
 -- (dictionaries).
 --
--- Since many function names (but not the type name) clash with
--- "Prelude" names, this module is usually imported @qualified@, e.g.
+-- 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 (although that is rarely needed).
+--
+-- These modules are intended to be imported qualified, to avoid name
+-- clashes with Prelude functions, e.g.
 --
--- >  import Data.Map.Lazy (Map)
 -- >  import qualified Data.Map.Lazy as Map
 --
 -- The implementation of 'Map' is based on /size balanced/ binary trees (or
@@ -37,7 +40,7 @@
 -- 'union' or 'insert'.
 --
 -- Operation comments contain the operation time complexity in
--- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
+-- the Big-O notation (<http://en.wikipedia.org/wiki/Big_O_notation>).
 -----------------------------------------------------------------------------
 
 module Data.Map.Lazy (
diff --git a/Data/Map/Strict.hs b/Data/Map/Strict.hs
index ee45153..c83d504 100644
--- a/Data/Map/Strict.hs
+++ b/Data/Map/Strict.hs
@@ -15,10 +15,13 @@
 -- An efficient implementation of ordered maps from keys to values
 -- (dictionaries).
 --
--- Since many function names (but not the type name) clash with
--- "Prelude" names, this module is usually imported @qualified@, e.g.
+-- 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 (although that is rarely needed).
+--
+-- These modules are intended to be imported qualified, to avoid name
+-- clashes with Prelude functions, e.g.
 --
--- >  import Data.Map.Strict (Map)
 -- >  import qualified Data.Map.Strict as Map
 --
 -- The implementation of 'Map' is based on /size balanced/ binary trees (or
@@ -37,7 +40,7 @@
 -- 'union' or 'insert'.
 --
 -- Operation comments contain the operation time complexity in
--- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
+-- the Big-O notation (<http://en.wikipedia.org/wiki/Big_O_notation>).
 -----------------------------------------------------------------------------
 
 -- It is crucial to the performance that the functions specialize on the Ord
@@ -266,10 +269,10 @@ import Data.Map.Base hiding
 --
 -- This module is strict in keys and values.  In particular,
 --
--- * key and value function arguments passed to functions are
---   evaluated to WHNF before the function body is evaluated, and
+-- * key and value arguments are evaluated to WHNF before the function
+--   body is evaluated, and
 --
--- * keys and values returned by high-order function arguments are
+-- * keys and values returned by higher-order function arguments are
 --   evaluated to WHNF before they are inserted into the map.
 --
 -- Here are some examples: