ouroboros-network-protocols: improved haddocks of node-to-node protocols

Author: coot

ouroboros-network-framework/src/Ouroboros/Network/Protocol/Handshake/Codec.hs

@@ -99,6 +99,14 @@ byteLimitsHandshake = ProtocolSizeLimits stateToLimit (fromIntegral . BL.length)
 
 -- | Time limits.
 --
+-- +--------------------+-------------+
+-- | 'Handshake' state  | timeout (s) |
+-- +====================+=============+
+-- | `StPropose`        | `shortWait` |
+-- +--------------------+-------------+
+-- | `StConfirm`        | `shortWait` |
+-- +--------------------+-------------+
+--
 timeLimitsHandshake :: forall vNumber. ProtocolTimeLimits (Handshake vNumber CBOR.Term)
 timeLimitsHandshake = ProtocolTimeLimits stateToLimit
   where
@@ -123,10 +131,9 @@ noTimeLimitsHandshake = ProtocolTimeLimits stateToLimit
 
 -- |
 -- @'Handshake'@ codec.  The @'MsgProposeVersions'@ encodes proposed map in
--- ascending order and it expects to receive them in this order.  This allows
--- to construct the map in linear time.  There is also another limiting factor
--- to the number of versions on can present: the whole message must fit into
--- a single TCP segment.
+-- ascending order and it expects to receive them in this order.  The whole
+-- `MsgProposeVersions` message must fit into a single TCP segment which limits
+-- number of versions that can be proposed.
 --
 codecHandshake
   :: forall vNumber m failure.
@@ -135,6 +142,7 @@ codecHandshake
      , Show failure
      )
   => CodecCBORTerm (failure, Maybe Int) vNumber
+  -- ^ `CBOR.Term` codec for `vNumber`
   -> Codec (Handshake vNumber CBOR.Term) CBOR.DeserialiseFailure m ByteString
 codecHandshake versionNumberCodec = mkCodecCborLazyBS encodeMsg decodeMsg
     where

ouroboros-network-protocols/src/Ouroboros/Network/Protocol/BlockFetch/Codec.hs

@@ -31,7 +31,7 @@ import Ouroboros.Network.Protocol.Limits
 
 -- | Byte Limit.
 byteLimitsBlockFetch :: forall bytes block point.
-                        (bytes -> Word)
+                        (bytes -> Word) -- ^ compute size of bytes
                      -> ProtocolSizeLimits (BlockFetch block point) bytes
 byteLimitsBlockFetch = ProtocolSizeLimits stateToLimit
   where
@@ -44,10 +44,16 @@ byteLimitsBlockFetch = ProtocolSizeLimits stateToLimit
 
 -- | Time Limits
 --
--- `TokIdle' No timeout
--- `TokBusy` `longWait` timeout
--- `TokStreaming` `longWait` timeout
-timeLimitsBlockFetch :: forall block point.
+-- +------------------+---------------+
+-- | BlockFetch state | timeout (s)   |
+-- +==================+===============+
+-- | `BFIdle`         | `waitForever` |
+-- +------------------+---------------+
+-- | `BFBusy`         | `longWait`    |
+-- +------------------+---------------+
+-- | `BFStreaming`    | `longWait`    |
+-- +------------------+---------------+
+--
                         ProtocolTimeLimits (BlockFetch block point)
 timeLimitsBlockFetch = ProtocolTimeLimits stateToLimit
   where
@@ -58,17 +64,21 @@ timeLimitsBlockFetch = ProtocolTimeLimits stateToLimit
     stateToLimit SingBFStreaming = longWait
     stateToLimit a@SingBFDone    = notActiveState a
 
--- | Codec for chain sync that encodes/decodes blocks
+-- | Codec for chain sync that encodes/decodes blocks and points.
 --
--- NOTE: See 'wrapCBORinCBOR' and 'unwrapCBORinCBOR' if you want to use this
+-- /NOTE:/ See 'wrapCBORinCBOR' and 'unwrapCBORinCBOR' if you want to use this
 -- with a block type that has annotations.
 codecBlockFetch
   :: forall block point m.
      MonadST m
   => (block            -> CBOR.Encoding)
+  -- ^ encode block
   -> (forall s. CBOR.Decoder s block)
+  -- ^ decode block
   -> (point -> CBOR.Encoding)
+  -- ^ encode point
   -> (forall s. CBOR.Decoder s point)
+  -- ^ decode point
   -> Codec (BlockFetch block point) CBOR.DeserialiseFailure m LBS.ByteString
 codecBlockFetch encodeBlock decodeBlock
                 encodePoint decodePoint =

ouroboros-network-protocols/src/Ouroboros/Network/Protocol/ChainSync/Codec.hs

@@ -17,7 +17,7 @@ module Ouroboros.Network.Protocol.ChainSync.Codec
 import Control.Monad.Class.MonadST
 import Control.Monad.Class.MonadTime.SI
 
-import Network.TypedProtocol.Codec.CBOR hiding (encode, decode)
+import Network.TypedProtocol.Codec.CBOR hiding (decode, encode)
 
 import Ouroboros.Network.Protocol.ChainSync.Type
 import Ouroboros.Network.Protocol.Limits
@@ -35,8 +35,8 @@ import Text.Printf
 
 
 -- | Byte Limits
-byteLimitsChainSync :: forall bytes header point tip .
-                       (bytes -> Word)
+byteLimitsChainSync :: forall bytes (header :: Type) (point :: Type) (tip :: Type) .
+                       (bytes -> Word) -- ^ compute size of `bytes`
                     -> ProtocolSizeLimits (ChainSync header point tip) bytes
 byteLimitsChainSync = ProtocolSizeLimits stateToLimit
   where
@@ -63,10 +63,21 @@ maxChainSyncTimeout = 269
 
 -- | Time Limits
 --
--- > 'TokIdle'               'waitForever' (ie never times out)
--- > 'TokNext TokCanAwait'   the given 'canAwaitTimeout'
--- > 'TokNext TokMustReply'  the given 'mustReplyTimeout'
--- > 'TokIntersect'          the given 'intersectTimeout'
+-- +----------------------------+-------------------------------------------------------------+
+-- | ChainSync State            | timeout (s)                                                 |
+-- +============================+=============================================================+
+-- | @'StIdle'@                 | 'waitForever' (i.e. never times out)                        |
+-- +----------------------------+-------------------------------------------------------------+
+-- | @'StNext' 'StCanAwait'@    | 'shortWait'                                                 |
+-- +----------------------------+-------------------------------------------------------------+
+-- | @'StNext' 'StMustReply'@   | randomly picked using uniform distribution from             |
+-- |                            | the range @('minChainSyncTimeout', 'maxChainSyncTimeout')@, |
+-- |                            | which corresponds to a chance of an empty streak of slots   |
+-- |                            | between `0.0001%` and `1%` probability.                     |
+-- +----------------------------+-------------------------------------------------------------+
+-- | @'StIntersect'@            | 'shortWait'                                                 |
+-- +----------------------------+-------------------------------------------------------------+
+--
 timeLimitsChainSync :: forall header point tip.
                        StdGen
                     -> ProtocolTimeLimits (ChainSync header point tip)
@@ -97,18 +108,26 @@ timeLimitsChainSync rnd = ProtocolTimeLimits stateToLimit
                   $ rnd
       in Just timeout
     stateToLimit a@SingDone = notActiveState a
+
+-- | Codec for chain sync that encodes/decodes headers, points & tips.
 --
--- NOTE: See 'wrapCBORinCBOR' and 'unwrapCBORinCBOR' if you want to use this
+-- /NOTE:/ See 'wrapCBORinCBOR' and 'unwrapCBORinCBOR' if you want to use this
 -- with a header type that has annotations.
 codecChainSync
   :: forall header point tip m.
      (MonadST m)
   => (header -> CBOR.Encoding)
+  -- ^ encode header
   -> (forall s . CBOR.Decoder s header)
+  -- ^ decode header
   -> (point -> CBOR.Encoding)
+  -- ^ encode point
   -> (forall s . CBOR.Decoder s point)
+  -- ^ decode point
   -> (tip -> CBOR.Encoding)
+  -- ^ encode tip
   -> (forall s. CBOR.Decoder s tip)
+  -- ^ decode tip
   -> Codec (ChainSync header point tip)
            CBOR.DeserialiseFailure m LBS.ByteString
 codecChainSync encodeHeader decodeHeader
@@ -230,7 +249,7 @@ decodeList dec = do
 -- | An identity 'Codec' for the 'ChainSync' protocol. It does not do any
 -- serialisation. It keeps the typed messages, wrapped in 'AnyMessage'.
 --
-codecChainSyncId :: forall header point tip m. Monad m
+codecChainSyncId :: forall (header :: Type) (point :: Type) (tip :: Type) m. Monad m
                  => Codec (ChainSync header point tip)
                           CodecFailure m (AnyMessage (ChainSync header point tip))
 codecChainSyncId = Codec encode decode

ouroboros-network-protocols/src/Ouroboros/Network/Protocol/KeepAlive/Codec.hs

@@ -86,6 +86,16 @@ byteLimitsKeepAlive = ProtocolSizeLimits sizeLimitForState
     sizeLimitForState a@SingDone = notActiveState a
 
 
+-- | 'KeepAlive' time limits.
+--
+-- +--------------------+---------------+
+-- | 'KeepAlive' state  | timeout (s)   |
+-- +====================+===============+
+-- | `StClient`         | @Just 97@     |
+-- +--------------------+---------------+
+-- | `StServer`         | @Just 60@     |
+-- +--------------------+---------------+
+--
 timeLimitsKeepAlive :: ProtocolTimeLimits KeepAlive
 timeLimitsKeepAlive = ProtocolTimeLimits { timeLimitForState }
   where

ouroboros-network-protocols/src/Ouroboros/Network/Protocol/PeerSharing/Codec.hs

@@ -26,11 +26,13 @@ import Ouroboros.Network.Protocol.PeerSharing.Type
 codecPeerSharing :: forall m peerAddress.
                     MonadST m
                  => (peerAddress -> CBOR.Encoding)
+                 -- ^ encode 'peerAddress'
                  -> (forall s . CBOR.Decoder s peerAddress)
+                 -- ^ decode 'peerAddress'
                  -> Codec (PeerSharing peerAddress)
-                         CBOR.DeserialiseFailure
-                         m
-                         ByteString
+                          CBOR.DeserialiseFailure
+                          m
+                          ByteString
 codecPeerSharing encodeAddress decodeAddress = mkCodecCborLazyBS encodeMsg decodeMsg
   where
     encodeMsg :: Message (PeerSharing peerAddress) st st'
@@ -120,7 +122,7 @@ maxTransmissionUnit :: Word
 maxTransmissionUnit = 4 * 1440
 
 byteLimitsPeerSharing :: forall peerAddress bytes.
-                         (bytes -> Word)
+                         (bytes -> Word) -- ^ compute size of bytes
                       -> ProtocolSizeLimits (PeerSharing peerAddress) bytes
 byteLimitsPeerSharing = ProtocolSizeLimits sizeLimitForState
   where
@@ -132,7 +134,16 @@ byteLimitsPeerSharing = ProtocolSizeLimits sizeLimitForState
     sizeLimitForState a@SingDone = notActiveState a
 
 
-timeLimitsPeerSharing :: forall peerAddress. ProtocolTimeLimits (PeerSharing peerAddress)
+-- | 'PeerSharing' timeouts.
+--
+-- +----------------------+---------------+
+-- | 'PeerSharing' state  | timeout (s)   |
+-- +======================+===============+
+-- | `StIdle`             | `waitForever` |
+-- +----------------------+---------------+
+-- | `StBusy`             | `longWait`    |
+-- +----------------------+---------------+
+--
 timeLimitsPeerSharing = ProtocolTimeLimits { timeLimitForState }
   where
     timeLimitForState :: forall (st :: PeerSharing peerAddress).

ouroboros-network-protocols/src/Ouroboros/Network/Protocol/TxSubmission2/Codec.hs

@@ -47,13 +47,22 @@ byteLimitsTxSubmission2 = ProtocolSizeLimits stateToLimit
     stateToLimit a@SingDone                  = notActiveState a
 
 
--- | Time Limits.
+-- | 'TxSubmission2' time limits.
+--
+-- +-----------------------------+---------------+
+-- | 'TxSubmission2' state       | timeout (s)   |
+-- +=============================+===============+
+-- | `StInit`                    | `waitForever` |
+-- +-----------------------------+---------------+
+-- | `StIdle`                    | `waitForever` |
+-- +-----------------------------+---------------+
+-- | @'StTxIds' 'StBlocking'@    | `waitForever` |
+-- +-----------------------------+---------------+
+-- | @'StTxIds' 'StNonBlocking'@ | `shortWait`   |
+-- +-----------------------------+---------------+
+-- | `StTxs`                     | `shortWait`   |
+-- +-----------------------------+---------------+
 --
--- `SingTxIds SingBlocking` No timeout
--- `SingTxIds SingNonBlocking` `shortWait` timeout
--- `SingTxs` `shortWait` timeout
--- `SingIdle` `shortWait` timeout
-timeLimitsTxSubmission2 :: forall txid tx. ProtocolTimeLimits (TxSubmission2 txid tx)
 timeLimitsTxSubmission2 = ProtocolTimeLimits stateToLimit
   where
     stateToLimit :: forall (st :: TxSubmission2 txid tx).
@@ -70,9 +79,13 @@ codecTxSubmission2
   :: forall txid tx m.
      MonadST m
   => (txid -> CBOR.Encoding)
+  -- ^ encode 'txid'
   -> (forall s . CBOR.Decoder s txid)
+  -- ^ decode 'txid'
   -> (tx -> CBOR.Encoding)
+  -- ^ encode transaction
   -> (forall s . CBOR.Decoder s tx)
+  -- ^ decode transaction
   -> Codec (TxSubmission2 txid tx) CBOR.DeserialiseFailure m ByteString
 codecTxSubmission2 encodeTxId decodeTxId
                    encodeTx   decodeTx =
@@ -90,16 +103,17 @@ codecTxSubmission2 encodeTxId decodeTxId
       decodeTxSubmission2 decodeTxId decodeTx stok len key
 
 encodeTxSubmission2
-    :: forall txid tx.
+    :: forall txid tx (st :: TxSubmission2 txid tx) (st' :: TxSubmission2 txid tx).
        (txid -> CBOR.Encoding)
+    -- ^ encode 'txid'
     -> (tx -> CBOR.Encoding)
-    -> (forall (st :: TxSubmission2 txid tx) (st' :: TxSubmission2 txid tx).
-               Message (TxSubmission2 txid tx) st st'
-            -> CBOR.Encoding)
+    -- ^ encode 'tx'
+    -> Message (TxSubmission2 txid tx) st st'
+    -> CBOR.Encoding
 encodeTxSubmission2 encodeTxId encodeTx = encode
   where
-    encode :: forall st st'.
-              Message (TxSubmission2 txid tx) st st'
+    encode :: forall st0 st1.
+              Message (TxSubmission2 txid tx) st0 st1
            -> CBOR.Encoding
     encode MsgInit =
         CBOR.encodeListLen 1
@@ -148,23 +162,24 @@ encodeTxSubmission2 encodeTxId encodeTx = encode
 
 
 decodeTxSubmission2
-    :: forall txid tx.
-       (forall s . CBOR.Decoder s txid)
-    -> (forall s . CBOR.Decoder s tx)
-    -> (forall (st :: TxSubmission2 txid tx) s.
-               ActiveState st
-            => StateToken st
-            -> Int
-            -> Word
-            -> CBOR.Decoder s (SomeMessage st))
+    :: forall (txid :: Type) (tx :: Type) (st :: TxSubmission2 txid tx) s.
+       ActiveState st
+    => (forall s'. CBOR.Decoder s' txid)
+    -- ^ decode 'txid'
+    -> (forall s'. CBOR.Decoder s' tx)
+    -- ^ decode transaction
+    -> StateToken st
+    -> Int
+    -> Word
+    -> CBOR.Decoder s (SomeMessage st)
 decodeTxSubmission2 decodeTxId decodeTx = decode
   where
-    decode :: forall s (st :: TxSubmission2 txid tx).
-              ActiveState st
-           => StateToken st
+    decode :: forall (st' :: TxSubmission2 txid tx).
+              ActiveState st'
+           => StateToken st'
            -> Int
            -> Word
-           -> CBOR.Decoder s (SomeMessage st)
+           -> CBOR.Decoder s (SomeMessage st')
     decode stok len key = do
       case (stok, len, key) of
         (SingInit,       1, 6) ->