Some documentation polish

Network/DNS/IO.hs

@@ -2,10 +2,10 @@
 {-# LANGUAGE OverloadedStrings #-}
 
 module Network.DNS.IO (
-    -- * Receiving from socket
+    -- * Receiving DNS messages
     receive
   , receiveVC
-    -- * Sending to socket
+    -- * Sending pre-encoded messages
   , send
   , sendVC
     -- ** Encoding queries for transmission
@@ -13,7 +13,7 @@ module Network.DNS.IO (
   , encodeQuestions'
   , composeQuery
   , composeQueryAD
-    -- ** Creating Response
+    -- ** Creating query response messages
   , responseA
   , responseAAAA
   ) where

Network/DNS/LookupRaw.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE RecordWildCards #-}
 
 module Network.DNS.LookupRaw (
-  -- * Looking up functions
+  -- * Lookups returning requested RData
     lookup
   , lookupAuth
   -- * Lookups returning DNS Messages
   , lookupRaw
   , lookupRaw'
   , lookupRawAD
+  -- * DNS Message procesing
   , fromDNSMessage
   , fromDNSFormat
   ) where
@@ -252,7 +253,17 @@ lookupRaw' rslv dom typ fl = resolve dom typ rslv fl receive
 
 ----------------------------------------------------------------
 
--- | Extract necessary information from 'DNSMessage'
+-- | Messages with a non-error RCODE are passed to the supplied function
+-- for processing.  Other messages are translated to 'DNSError' instances.
+--
+-- Note that 'NameError' is not a lookup error.  The lookup is successful,
+-- bearing the sad news that the requested domain does not exist.  'NameError'
+-- resposes may return a meaningful AD bit, may contain useful data in the
+-- authority section, and even initial CNAME records that lead to the
+-- ultimately non-existent domain.  Applications that wish to process the
+-- content of 'NameError' (NXDomain) messages will need to implement their
+-- own RCODE handling.
+--
 fromDNSMessage :: DNSMessage -> (DNSMessage -> a) -> Either DNSError a
 fromDNSMessage ans conv = case errcode ans of
     NoErr     -> Right $ conv ans

Network/DNS/Types.hs

@@ -52,8 +52,19 @@ module Network.DNS.Types (
   -- ** DNS Header
   , DNSHeader (..)
   , Identifier
+  -- *** DNS flags
+  , DNSFlags (..)
   , QorR (..)
+  , defaultDNSFlags
+  , QueryFlags
+  , queryDNSFlags
+  , rdBit
+  , adBit
+  , cdBit
+  -- **** OPCODE and RCODE
   , OPCODE (..)
+  , fromOPCODE
+  , toOPCODE
   , RCODE (
     NoErr
   , FormatErr
@@ -68,17 +79,6 @@ module Network.DNS.Types (
   , NotZone
   , BadOpt
   )
-  -- *** DNS flags
-  , DNSFlags (..)
-  , defaultDNSFlags
-  , QueryFlags
-  , queryDNSFlags
-  , rdBit
-  , adBit
-  , cdBit
-  -- **** OPCODE and RCODE
-  , fromOPCODE
-  , toOPCODE
   , fromRCODE
   , toRCODE
   , fromRCODEforHeader
@@ -443,6 +443,8 @@ defaultDNSFlags = DNSFlags
 -- yield all possible combinations of "set", "clear" and "reset" (to default)
 -- for each of the bits.
 --
+-- ==== __Example__
+--
 -- >>> :{
 -- let setrd = rdBit (Just True)
 --     setad = adBit (Just True)
@@ -542,6 +544,8 @@ data OPCODE
   | OP_UPDATE -- ^ An update request (RFC2136)
   deriving (Eq, Show, Enum, Bounded)
 
+-- | Convert a 16-bit DNS OPCODE number to its internal representation
+--
 toOPCODE :: Word16 -> Maybe OPCODE
 toOPCODE i = case i of
   0 -> Just OP_STD
@@ -551,6 +555,9 @@ toOPCODE i = case i of
   5 -> Just OP_UPDATE
   _ -> Nothing
 
+-- | Convert the internal representation of a DNS OPCODE to its 16-bit numeric
+-- value.
+--
 fromOPCODE :: OPCODE -> Word16
 fromOPCODE OP_STD    = 0
 fromOPCODE OP_INV    = 1