text-postgresql: update haddock.

text-postgresql/src/Data/PostgreSQL/NetworkAddress.hs

@@ -10,9 +10,13 @@
 -- This module defines network-address types of PostgreSQL.
 -- http://www.postgresql.org/docs/current/static/datatype-net-types.html
 module Data.PostgreSQL.NetworkAddress
-       (
-         Inet (..), Cidr (..), cidr4', cidr4, cidr6', cidr6,
+       ( -- * Definitions about inet and cidr types
+         Inet (..), Cidr (..), cidr4, cidr4', cidr6, cidr6',
+
+         -- * Definitions about the address type which is the pair of host-address and mask
          NetAddress (..), netAddress4, netAddress6,
+
+         -- * Definitions about the host-address types
          V4HostAddress (..), v4HostAddressOctets,
          V6HostAddress (..), v6HostAddressLong, v6HostAddressWords,
          v6HostAddress, v6HostAddressL, v6HostAddressR,
@@ -24,7 +28,7 @@ import Data.Word (Word8, Word16, Word32)
 import Data.Bits (shiftL, shiftR, (.&.), (.|.))
 
 
--- | Host address type along with IPv4 address string.
+-- | Host address type along with IPv4 address bytes with IPv4 string order.
 data V4HostAddress =
   V4HostAddress !Word8 !Word8 !Word8 !Word8
   deriving (Eq, Ord, Show, Read)
@@ -33,7 +37,7 @@ v4HostAddressOctets :: V4HostAddress -> (Word8, Word8, Word8, Word8)
 v4HostAddressOctets (V4HostAddress a b c d) = (a, b, c, d)
 
 
--- | Host address type along with IPv6 address string.
+-- | Host address type along with IPv6 address words with IPv6 string order.
 --   Each 'Word16' value is host byte order.
 --   Host byte order is portable in programs on its own host.
 --   Network byte order is only needed, when communicating other hosts.
@@ -63,7 +67,8 @@ v6HostAddressWords :: V6HostAddress -> (Word16, Word16, Word16, Word16, Word16,
 v6HostAddressWords (V6HostAddress a b c d e f g h) =
   (a, b, c, d, e, f, g, h)
 
-
+-- | IPv4 or IPv6 netword address corresponding <host-addr>/<mask>.
+--   eg. '192.168.0.1/24'
 data NetAddress
   = NetAddress4 !V4HostAddress !Word8
   | NetAddress6 !V6HostAddress !Word8
@@ -72,7 +77,10 @@ data NetAddress
 vmask4 :: (Ord a, Integral a) => a -> Bool
 vmask4 = (<= 32)
 
-netAddress4 :: V4HostAddress -> Word8 -> Maybe NetAddress
+-- | Make IPv4 NetAddress type consistent with IPv4 mask
+netAddress4 :: V4HostAddress     -- ^ IPv4 host-address
+            -> Word8             -- ^ IPv4 mask 0-32
+            -> Maybe NetAddress  -- ^ result NetAddress
 netAddress4 a4 m
   | vmask4 m   =  Just $ NetAddress4 a4 m
   | otherwise  =  Nothing
@@ -80,13 +88,18 @@ netAddress4 a4 m
 vmask6 :: (Ord a, Integral a) => a -> Bool
 vmask6 = (<= 128)
 
-netAddress6 :: V6HostAddress -> Word8 -> Maybe NetAddress
+-- | Make IPv6 NetAddress type consistent with IPv6 mask
+netAddress6 :: V6HostAddress     -- ^ IPv6 host-address
+            -> Word8             -- ^ IPv6 mask 0-128
+            -> Maybe NetAddress  -- ^ result NetAddress
 netAddress6 a6 m
   | vmask6 m   =  Just $ NetAddress6 a6 m
   | otherwise  =  Nothing
 
+-- | Corresponding to INET type of PostgreSQL
 newtype Inet = Inet NetAddress  deriving (Eq, Ord, Show, Read)
 
+-- | Corresponding to CIDR type of PostgreSQL
 newtype Cidr = Cidr NetAddress  deriving (Eq, Ord, Show, Read)
 
 maskCidr4 :: V4HostAddress -> Word8 -> (Word32, Word32)
@@ -100,6 +113,7 @@ maskCidr4 (V4HostAddress w0 w1 w2 w3) m =
          [w3, w2, w1, w0]
          [0,8 ..]
 
+-- | Same as cidr4 except for dropping host-address bits along with mask
 cidr4' :: V4HostAddress -> Word8 -> Maybe Cidr
 cidr4' ha0 m = do
     guard $ vmask4 m
@@ -111,6 +125,7 @@ cidr4' ha0 m = do
     fromList4 ws = V4HostAddress w0 w1 w2 w3
       where [w0, w1, w2, w3] = ws
 
+-- | Make Cidr type of IPv4 from host-address bits consistent with mask
 cidr4 :: V4HostAddress -> Word8 -> Maybe Cidr
 cidr4 ha m = do
   na <- netAddress4 ha m
@@ -129,6 +144,7 @@ maskCidr6 (V6HostAddress w0 w1 w2 w3 w4 w5 w6 w7) m =
          [w7, w6, w5, w4, w3, w2, w1, w0]
          [0,16 ..]
 
+-- | Same as cidr6 except for dropping host-address bits along with mask
 cidr6' :: V6HostAddress -> Word8 -> Maybe Cidr
 cidr6' ha0 m = do
     guard $ vmask6 m
@@ -140,6 +156,7 @@ cidr6' ha0 m = do
     fromList6 ws = V6HostAddress w0 w1 w2 w3 w4 w5 w6 w7
       where [w0, w1, w2, w3, w4, w5, w6, w7] = ws
 
+-- | Make Cidr type of IPv6 from host-address bits consistent with mask
 cidr6 :: V6HostAddress -> Word8 -> Maybe Cidr
 cidr6 ha m = do
   na <- netAddress6 ha m