Improve Data.Set module docs. (#502)
authorMatt Renaud <matt@m-renaud.com>
Mon, 22 Jan 2018 18:05:33 +0000 (10:05 -0800)
committerDavid Feuer <David.Feuer@gmail.com>
Mon, 22 Jan 2018 18:05:33 +0000 (13:05 -0500)
* Improve Data.Set module docs.

[ci skip]

* Move strictness properties into module docs.

[ci skip]

* Address review comments.

[ci skip]

* Reword first paragraph.

[ci skip]

Data/Set.hs

index c0396b0..ff07475 100644 (file)
 -- Maintainer  :  libraries@haskell.org
 -- Portability :  portable
 --
--- An efficient implementation of sets.
+--
+-- = Finite Sets
+--
+-- The @'Set' e@ type represents a set of elements of type @e@. Most operations
+-- require that @e@ be an instance of the 'Ord' class. A 'Set' is strict in its
+-- elements.
+--
+-- For a walkthrough of the most commonly used functions see the
+-- <https://haskell-containers.readthedocs.io/en/latest/set.html sets introduction>.
+--
+-- Note that the implementation is generally /left-biased/. Functions that take
+-- two sets as arguments and combine them, such as `union` and `intersection`,
+-- prefer the entries in the first argument to those in the second. Of course,
+-- this bias can only be observed when equality is an equivalence relation
+-- instead of structural equality.
 --
 -- These modules are intended to be imported qualified, to avoid name
 -- clashes with Prelude functions, e.g.
 -- >  import Data.Set (Set)
 -- >  import qualified Data.Set as Set
 --
+--
+-- == Warning
+--
+-- The size of the set must not exceed @maxBound::Int@. Violation of
+-- this condition is not detected and if the size limit is exceeded, its
+-- behaviour is undefined.
+--
+--
+-- == Implementation
+--
 -- The implementation of 'Set' is based on /size balanced/ binary trees (or
 -- trees of /bounded balance/) as described by:
 --
 --      \"/Just Join for Parallel Ordered Sets/\",
 --      <https://arxiv.org/abs/1602.02120v3>.
 --
--- 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'.  Of course, left-biasing can only be observed
--- when equality is an equivalence relation instead of structural
--- equality.
---
--- /Warning/: The size of the set must not exceed @maxBound::Int@. Violation of
--- this condition is not detected and if the size limit is exceeded, its
--- behaviour is undefined.
 -----------------------------------------------------------------------------
 
 module Data.Set (
-            -- * Strictness properties
-            -- $strictness
-
             -- * Set type
 #if !defined(TESTING)
               Set          -- instance Eq,Ord,Show,Read,Data,Typeable
@@ -165,13 +177,3 @@ module Data.Set (
             ) where
 
 import Data.Set.Internal as S
-
--- $strictness
---
--- This module satisfies the following strictness property:
---
--- * Key arguments are evaluated to WHNF
---
--- Here are some examples that illustrate the property:
---
--- > delete undefined s  ==  undefined