[CDEC-439] updated & spellchecked comments

Author: coot

networking/src/Ntp/Client.hs

@@ -51,7 +51,7 @@ import           Ntp.Util (AddrFamily (..), Addresses, EitherOrBoth (..),
 import           Pos.Util.Trace (traceWith)
 
 data NtpStatus =
-      -- | The difference between ntp time and local system time
+      -- | The difference between NTP time and local system time
       NtpDrift NtpOffset
       -- | NTP client has send requests to the servers
     | NtpSyncPending
@@ -164,12 +164,12 @@ sendLoop cli addrs = do
 
     () <- withAsync
         (do
-            -- wait for reponses and update status
+            -- wait for responses and update status
             _ <- timeout respTimeout waitForResponses
             updateStatus cli
         )
         (\a -> do
-            -- send packets and wait untill end of poll delay
+            -- send packets and wait until end of poll delay
             sock <- atomically $ readTVar $ ncSockets cli
             pack <- mkNtpPacket
             sendPacket sock pack addrs
@@ -193,7 +193,7 @@ sendLoop cli addrs = do
             logDebug "collected all responses"
 
 -- |
--- Start listening for responses on the socket `ncSockets
+-- Start listening for responses on the socket @'ncSockets'@
 startReceive :: NtpClient -> IO ()
 startReceive cli =
     atomically (readTVar $ ncSockets cli) >>= \case
@@ -206,7 +206,7 @@ startReceive cli =
         EBSecond (Last (WithIPv4 sock_ipv4)) ->
             loop IPv4 sock_ipv4
     where
-    -- Receive responses from the network and update ntp client state.
+    -- Receive responses from the network and update NTP client state.
     loop :: AddrFamily -> Socket.Socket -> IO ()
     loop addressFamily sock
         = handle (handleIOException addressFamily) $ forever $ do
@@ -217,7 +217,7 @@ startReceive cli =
                 Right (_, _, packet) ->
                     handleNtpPacket packet
 
-    -- Restart the @loop@ in case of errors; wait 5s before recreacting the
+    -- Restart the @loop@ in case of errors; wait 5s before recreating the
     -- socket.
     handleIOException
         :: AddrFamily
@@ -238,8 +238,8 @@ startReceive cli =
                     EBBoth _ _
                         -> error "NtpClient: startReceive: impossible"
 
-    -- Compute the clock offset based on current time and record it in the ntp
-    -- client state.   A packet will be digarded if it came after
+    -- Compute the clock offset based on current time and record it in the NTP
+    -- client state.   A packet will be disgarded if it came after
     -- @'ntpResponseTimeout'@.
     handleNtpPacket
         :: NtpPacket
@@ -256,10 +256,10 @@ startReceive cli =
                 atomically $ modifyTVar' (ncState cli) ( offset : )
 
 -- |
--- Spawn ntp client which will send request to ntp servers every ntpPollDelay
--- and will lisent for responses.  The `ncStatus` will be updated every
--- `ntpPollDelay` with the most recent value.  It should be run in a seprate
--- thread, since it will block infinitelly.
+-- Spawn NTP client which will send request to NTP servers every @'ntpPollDelay'@
+-- and will listen for responses.  The @'ncStatus'@ will be updated every
+-- @'ntpPollDelay'@ with the most recent value.  It should be run in a separate
+-- thread, since it will block infinitely.
 spawnNtpClient :: NtpClientSettings -> TVar NtpStatus -> IO ()
 spawnNtpClient settings ncStatus = do
     logInfo "starting"
@@ -281,16 +281,16 @@ spawnNtpClient settings ncStatus = do
     fn (Last sock) = Socket.close $ runWithAddrFamily sock
 
 -- |
--- Run Ntp client in a seprate thread; it returns a mutable cell which holds
--- `NtpStatus`.
+-- Run NTP client in a separate thread; it returns a mutable cell which holds
+-- @'NtpStatus'@.
 --
--- This function should be called once, it will run an ntp client in a new
--- thread untill the program terminates.
+-- This function should be called once, it will run an NTP client in a new
+-- thread until the program terminates.
 withNtpClient :: MonadIO m => NtpClientSettings -> m (TVar NtpStatus)
 withNtpClient ntpSettings = do
     liftIO $ logInfo "withNtpClient"
     ncStatus <- newTVarIO NtpSyncPending
-    -- using async so the ntp thread will be left running even if the parent
+    -- using async so the NTP thread will be left running even if the parent
     -- thread finished.
     _ <- liftIO $ async (spawnNtpClient ntpSettings ncStatus)
     return ncStatus

networking/src/Ntp/Packet.hs

@@ -51,7 +51,7 @@ instance Binary NtpPacket where
         ntpPoll   <- getInt8
         _         <- getWord8
 
-        -- skip 5 `Word32` words
+        -- skip 5 @'Word32'@ words
         skip 20
 
         ntpOriginTime   <- getTimestamp
@@ -76,9 +76,9 @@ ntpPacketSize :: Int
 ntpPacketSize = 48
 
 -- |
--- For pairs `(x, y) :: (Word32, Word32)` with `y \`mod\` 4294 == 0` it is
--- be righ inverse of `realMsgToNtp`.   In general it is not injective (for that
--- we'd need to use `Picosecond` insteaed of `Microsecond`).
+-- For pairs @(x, y) :: (Word32, Word32)@ with @y \`mod\` 4294 == 0@ it is
+-- be right inverse of @'realMsgToNtp'@.   In general it is not injective (for that
+-- we'd need to use @'Picosecond'@ instead of @'Microsecond'@).
 ntpToRealMcs :: Word32 -> Word32 -> Microsecond
 ntpToRealMcs sec frac =
     let -- microseconds
@@ -91,7 +91,7 @@ ntpToRealMcs sec frac =
     in fromMicroseconds $ secMicro + fracMicro
 
 -- |
--- It is a partial function, since `Microsecond ~ Integer`; it is well defined
+-- It is a partial function, since @Microsecond ~ Integer@; it is well defined
 -- for:
 -- @
 --  x < 2085978496 = (maxBound @Word32 * 1000000) - ntpTimestampDelta + 1`
@@ -104,7 +104,7 @@ realMcsToNtp (toMicroseconds -> mcs) =
         , fromIntegral $ frac * 4294)
 
 -- |
--- Smart constructor for @NptPacket@.
+-- Smart constructor for @'NtpPacket'@.
 mkNtpPacket :: IO NtpPacket
 mkNtpPacket = do
     let ntpParams       = 0x1b
@@ -115,23 +115,21 @@ mkNtpPacket = do
     return NtpPacket{..}
 
 -- |
--- NtpOffset is the difference between ntp time and localtime
+-- @'NtpOffset'@ is the difference between NTP time and local time.
 newtype NtpOffset = NtpOffset { getNtpOffset :: Microsecond }
     deriving (Enum, Eq, Integral, Num, Ord, Real, Show, TimeUnit)
 
--- |
--- TODO: add a test
 clockOffsetPure :: NtpPacket -> Microsecond -> NtpOffset
 clockOffsetPure NtpPacket{..} localTime = NtpOffset
     $ (ntpReceivedTime - ntpOriginTime + ntpTransmitTime - localTime)
       `div` 2
 
 -- |
--- Compute clock offset unless the ntp packet was requested more than the given
+-- Compute clock offset unless the NTP packet was requested more than the given
 -- timeout.
 clockOffset
     :: Microsecond
-    -- ^ @'ntpResponseTimeout'@, ignore reponses which come after it passed.
+    -- ^ @'ntpResponseTimeout'@, ignore responses which come after it passed.
     -> NtpPacket
     -> IO (Maybe NtpOffset)
 clockOffset respTimeout packet = do

networking/src/Ntp/Util.hs

@@ -176,9 +176,9 @@ resolveHost :: String -> IO (Maybe Addresses)
 resolveHost host = do
     let hints = Socket.defaultHints
             { addrSocketType = Datagram
-            , addrFlags = [AI_ADDRCONFIG]  -- since we use AF_INET family
+            , addrFlags = [AI_ADDRCONFIG]  -- since we use @AF_INET@ family
             }
-    -- TBD why catch here? Why not let 'resolveHost' throw the exception?
+    -- TBD why catch here? Why not let @'resolveHost'@ throw the exception?
     addrInfos <- Socket.getAddrInfo (Just hints) (Just host) Nothing
                     `catch` (\(_ :: IOException) -> return [])
 
@@ -219,7 +219,7 @@ replacePort _    sockAddr                          = sockAddr
 
 createAndBindSock
     :: AddrFamily
-    -- ^ indicates which socket family to create, either AF_INET6 or AF_INET
+    -- ^ indicates which socket family to create, either @AF_INET6@ or @AF_INET@
     -> [AddrInfo]
     -- ^ list of local addresses
     -> IO (Maybe Sockets)
@@ -284,7 +284,7 @@ sendTo sock bs addr = case fmap (foldEitherOrBoth . bimap fn fn) $ pairEitherOrB
     handleIOException addressFamily e = throw (SendToIOException addressFamily e)
 
 -- |
--- Low level primitive which sends a request to a single ntp server.
+-- Low level primitive which sends a request to a single NTP server.
 sendPacket
     :: Sockets
     -> NtpPacket
@@ -299,7 +299,6 @@ sendPacket sock packet addrs = do
         )
         addrs
   where
-    -- just log; socket closure is handled by receiver
     handleSendToException :: Addresses -> SendToException -> IO ()
     handleSendToException addr e@NoMatchingSocket =
         logError $ sformat