Document NameSet

diff --git a/compiler/basicTypes/NameSet.lhs b/compiler/basicTypes/NameSet.lhs
index e60ea23..7eb5da5 100644 (file)
--- a/compiler/basicTypes/NameSet.lhs
+++ b/compiler/basicTypes/NameSet.lhs
@@ -5,19 +5,26 @@
 
 \begin{code}
 module NameSet (
 
 \begin{code}
 module NameSet (

-       -- Sets of Names
+       -- * Names set type

        NameSet,
        NameSet,

+       
+       -- ** Manipulating these sets

        emptyNameSet, unitNameSet, mkNameSet, unionNameSets, unionManyNameSets,
        minusNameSet, elemNameSet, nameSetToList, addOneToNameSet, addListToNameSet, 
        delFromNameSet, delListFromNameSet, isEmptyNameSet, foldNameSet, filterNameSet,
        intersectsNameSet, intersectNameSet,
        
        emptyNameSet, unitNameSet, mkNameSet, unionNameSets, unionManyNameSets,
        minusNameSet, elemNameSet, nameSetToList, addOneToNameSet, addListToNameSet, 
        delFromNameSet, delListFromNameSet, isEmptyNameSet, foldNameSet, filterNameSet,
        intersectsNameSet, intersectNameSet,
        

-       -- Free variables
-       FreeVars, isEmptyFVs, emptyFVs, plusFVs, plusFV, 
+       -- * Free variables
+       FreeVars,
+       
+       -- ** Manipulating sets of free variables
+       isEmptyFVs, emptyFVs, plusFVs, plusFV, 

        mkFVs, addOneFV, unitFV, delFV, delFVs,
 
        mkFVs, addOneFV, unitFV, delFV, delFVs,
 

-       -- Defs and uses
+       -- * Defs and uses

        Defs, Uses, DefUse, DefUses,
        Defs, Uses, DefUse, DefUses,

+       
+       -- ** Manipulating defs and uses

        emptyDUs, usesOnly, mkDUs, plusDU, 
        findUses, duDefs, duUses, allUses
     ) where
        emptyDUs, usesOnly, mkDUs, plusDU, 
        findUses, duDefs, duUses, allUses
     ) where

@@ -36,6 +43,7 @@ import UniqSet
 
 \begin{code}
 type NameSet = UniqSet Name
 
 \begin{code}
 type NameSet = UniqSet Name

+

 emptyNameSet      :: NameSet
 unitNameSet       :: Name -> NameSet
 addListToNameSet   :: NameSet -> [Name] -> NameSet
 emptyNameSet      :: NameSet
 unitNameSet       :: Name -> NameSet
 addListToNameSet   :: NameSet -> [Name] -> NameSet

@@ -52,8 +60,9 @@ delListFromNameSet :: NameSet -> [Name] -> NameSet
 foldNameSet       :: (Name -> b -> b) -> b -> NameSet -> b
 filterNameSet     :: (Name -> Bool) -> NameSet -> NameSet
 intersectNameSet   :: NameSet -> NameSet -> NameSet
 foldNameSet       :: (Name -> b -> b) -> b -> NameSet -> b
 filterNameSet     :: (Name -> Bool) -> NameSet -> NameSet
 intersectNameSet   :: NameSet -> NameSet -> NameSet

-intersectsNameSet  :: NameSet -> NameSet -> Bool       -- True if non-empty intersection
-       -- (s1 `intersectsNameSet` s2) doesn't compute s2 if s1 is empty
+intersectsNameSet  :: NameSet -> NameSet -> Bool
+-- ^ True if there is a non-empty intersection.
+-- @s1 `intersectsNameSet` s2@ doesn't compute @s2@ if @s1@ is empty

 
 isEmptyNameSet    = isEmptyUniqSet
 emptyNameSet     = emptyUniqSet
 
 isEmptyNameSet    = isEmptyUniqSet
 emptyNameSet     = emptyUniqSet

@@ -117,21 +126,23 @@ delFVs ns s = delListFromNameSet s ns
 %************************************************************************
 
 \begin{code}
 %************************************************************************
 
 \begin{code}

+-- | A set of names that are defined somewhere

 type Defs = NameSet
 type Defs = NameSet

-type Uses = NameSet

 
 

-type DefUses = [DefUse]
-       -- In dependency order: earlier Defs scope over later Uses
+-- | A set of names that are used somewhere
+type Uses = NameSet

 
 

+-- | @(Just ds, us) =>@ The use of any member of the @ds@
+--                      implies that all the @us@ are used too.
+--                      Also, @us@ may mention @ds@.
+--
+-- @Nothing =>@ Nothing is defined in this group, but
+--             nevertheless all the uses are essential.
+--             Used for instance declarations, for example

 type DefUse  = (Maybe Defs, Uses)
 type DefUse  = (Maybe Defs, Uses)

-       -- For items (Just ds, us), the use of any member 
-       -- of the ds implies that all the us are used too
-       --
-       -- Also, us may mention ds
-       --
-       -- Nothing => Nothing defined in this group, but
-       --            nevertheless all the uses are essential.
-       --            Used for instance declarations, for example
+
+-- | A number of 'DefUse's in dependency order: earlier 'Defs' scope over later 'Uses'
+type DefUses = [DefUse]

 
 emptyDUs :: DefUses
 emptyDUs = []
 
 emptyDUs :: DefUses
 emptyDUs = []

@@ -152,15 +163,14 @@ duDefs dus = foldr get emptyNameSet dus
     get (Just d1, _u1) d2 = d1 `unionNameSets` d2
 
 duUses :: DefUses -> Uses
     get (Just d1, _u1) d2 = d1 `unionNameSets` d2
 
 duUses :: DefUses -> Uses

--- Just like allUses, but defs are not eliminated
+-- ^ Just like 'allUses', but 'Defs' are not eliminated from the 'Uses' returned

 duUses dus = foldr get emptyNameSet dus
   where
     get (_d1, u1) u2 = u1 `unionNameSets` u2
 
 allUses :: DefUses -> Uses
 duUses dus = foldr get emptyNameSet dus
   where
     get (_d1, u1) u2 = u1 `unionNameSets` u2
 
 allUses :: DefUses -> Uses

--- Collect all uses, regardless of
--- whether the group is itself used,
--- but remove defs on the way
+-- ^ Collect all 'Uses', regardless of whether the group is itself used,
+-- but remove 'Defs' on the way

 allUses dus
   = foldr get emptyNameSet dus
   where
 allUses dus
   = foldr get emptyNameSet dus
   where

@@ -169,11 +179,9 @@ allUses dus
                                     `minusNameSet` defs
 
 findUses :: DefUses -> Uses -> Uses
                                     `minusNameSet` defs
 
 findUses :: DefUses -> Uses -> Uses

--- Given some DefUses and some Uses, 
--- find all the uses, transitively. 
--- The result is a superset of the input uses;
--- and includes things defined in the input DefUses
--- (but only if they are used)
+-- ^ Given some 'DefUses' and some 'Uses', find all the uses, transitively.
+-- The result is a superset of the input 'Uses'; and includes things defined 
+-- in the input 'DefUses' (but only if they are used)

 findUses dus uses 
   = foldr get uses dus
   where
 findUses dus uses 
   = foldr get uses dus
   where