[project @ 2005-01-17 11:23:25 by ross]

doc tweaks

diff --git a/Data/Ix.hs b/Data/Ix.hs
index 1a64152..6af2c19 100644 (file)
--- a/Data/Ix.hs
+++ b/Data/Ix.hs
@@ -8,27 +8,14 @@
 -- Stability   :  stable
 -- Portability :  portable
 --
--- Class of index types.
---
--- The 'Ix' class is used to map a continuous subrange of values in a type onto
--- integers. It is used primarily for array indexing (see Section 6
--- <http://www.haskell.org/onlinelibrary/array.html#arrays>). The 'Ix'
--- class contains the methods range, index, and inRange. The 'index' operation
--- maps a bounding pair, which defines the lower and upper bounds of the range,
--- and a subscript, to an integer. The 'range' operation enumerates all
--- subscripts; the 'inRange' operation tells whether a particular subscript
--- lies in the range defined by a bounding pair.
--- 
--- An implementation is entitled to assume the following laws about these
--- operations: 
--- 
--- >        range (l,u) !! index (l,u) i == i   -- when i is in range
--- 
--- >        inRange (l,u) i == i `elem` range (l,u)
+-- The 'Ix' class is used to map a contiguous subrange of values in
+-- type onto integers.  It is used primarily for array indexing
+-- (see "Data.Array", "Data.Array.IArray" and "Data.Array.MArray").
 -- 
 -----------------------------------------------------------------------------
 module Data.Ix
     (
+    -- * The 'Ix' class
        Ix
          ( range       -- :: (Ix a) => (a,a) -> [a]
          , index       -- :: (Ix a) => (a,a) -> a   -> Int
@@ -48,7 +35,7 @@ module Data.Ix
 
     -- Implementation checked wrt. Haskell 98 lib report, 1/99.
 
-    -- * Deriving Instances of Ix
+    -- * Deriving Instances of 'Ix'
     -- | Derived instance declarations for the class 'Ix' are only possible
     -- for enumerations (i.e. datatypes having only nullary constructors)
     -- and single-constructor datatypes, including arbitrarily large tuples,

diff --git a/GHC/Arr.lhs b/GHC/Arr.lhs
index ede18bc..b376c2f 100644 (file)
--- a/GHC/Arr.lhs
+++ b/GHC/Arr.lhs
@@ -37,11 +37,46 @@ default ()
 %*********************************************************
 
 \begin{code}
+-- | The 'Ix' class is used to map a contiguous subrange of values in
+-- a type onto integers.  It is used primarily for array indexing
+-- (see "Data.Array", "Data.Array.IArray" and "Data.Array.MArray").
+--
+-- The first argument @(l,u)@ of each of these operations is a pair
+-- specifying the lower and upper bounds of a contiguous subrange of values.
+--
+-- An implementation is entitled to assume the following laws about these
+-- operations:
+--
+-- * @'inRange' (l,u) i == 'elem' i ('range' (l,u))@
+--
+-- * @'range' (l,u) '!!' 'index' (l,u) i == i@, when @'inRange' (l,u) i@
+--
+-- * @'map' ('index' (l,u)) ('range' (l,u))) == [0..'rangeSize' (l,u)-1]@
+--
+-- * @'rangeSize' (l,u) == 'length' ('range' (l,u))@
+--
+-- Minimal complete instance: 'range', 'index' and 'inRange'.
+--
 class (Ord a) => Ix a where
+    -- | The list of values in the subrange defined by a bounding pair.
     range              :: (a,a) -> [a]
-    index, unsafeIndex :: (a,a) -> a -> Int
+    -- | The position of a subscript in the subrange.
+    index              :: (a,a) -> a -> Int
+    -- | Like 'index', but without checking that the value is in range.
+    unsafeIndex                :: (a,a) -> a -> Int
+    -- | Returns 'True' the given subscript lies in the range defined
+    -- the bounding pair.
     inRange            :: (a,a) -> a -> Bool
+    -- | The size of the subrange defined by a bounding pair.
     rangeSize          :: (a,a) -> Int
+    -- | like 'rangeSize', but without checking that the upper bound is
+    -- in range.
+    --
+    -- As long as you don't override the default 'rangeSize', you can
+    -- specify 'unsafeRangeSize' as follows, to speed up some operations:
+    --
+    -- >  unsafeRangeSize b@(_l,h) = unsafeIndex b h + 1
+    --
     unsafeRangeSize     :: (a,a) -> Int
 
        -- Must specify one of index, unsafeIndex
@@ -49,12 +84,6 @@ class (Ord a) => Ix a where
              | otherwise   = error "Error in array index"
     unsafeIndex b i = index b i
 
-       -- As long as you don't override the default rangeSize, 
-       -- you can specify unsafeRangeSize as follows, to speed up
-       -- some operations:
-       --
-       --    unsafeRangeSize b@(_l,h) = unsafeIndex b h + 1
-       --
     rangeSize b@(_l,h) | inRange b h = unsafeIndex b h + 1
                       | otherwise   = 0
     unsafeRangeSize b = rangeSize b