Improved haddocks, removed unused pragmas (extensions)

Author: coot

typed-protocols-cborg/src/Network/TypedProtocol/Codec/CBOR.hs

@@ -1,17 +1,19 @@
 {-# LANGUAGE DataKinds           #-}
 {-# LANGUAGE FlexibleContexts    #-}
+{-# LANGUAGE LambdaCase          #-}
 {-# LANGUAGE MonoLocalBinds      #-}
 {-# LANGUAGE PolyKinds           #-}
 {-# LANGUAGE RankNTypes          #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
 module Network.TypedProtocol.Codec.CBOR
   ( module Network.TypedProtocol.Codec
-  , DeserialiseFailure
   , mkCodecCborLazyBS
   , mkCodecCborStrictBS
   , convertCborDecoderBS
   , convertCborDecoderLBS
+    -- * Re-exports
+  , CBOR.DeserialiseFailure (..)
   ) where
 
 import           Control.Monad.Class.MonadST (MonadST (..))
@@ -31,8 +33,6 @@ import           Network.TypedProtocol.Codec
 import           Network.TypedProtocol.Core
 
 
-type DeserialiseFailure = CBOR.DeserialiseFailure
-
 -- | Construct a 'Codec' for a CBOR based serialisation format, using strict
 -- 'BS.ByteString's.
 --
@@ -52,13 +52,15 @@ mkCodecCborStrictBS
              StateTokenI st
           => ActiveState st
           => Message ps st st' -> CBOR.Encoding)
+  -- ^ cbor encoder
 
   -> (forall (st :: ps) s.
              ActiveState st
           => StateToken st
           -> CBOR.Decoder s (SomeMessage st))
+  -- ^ cbor decoder
 
-  -> Codec ps DeserialiseFailure m BS.ByteString
+  -> Codec ps CBOR.DeserialiseFailure m BS.ByteString
 mkCodecCborStrictBS cborMsgEncode cborMsgDecode =
     Codec {
       encode = \msg  -> convertCborEncoder cborMsgEncode msg,
@@ -72,19 +74,21 @@ mkCodecCborStrictBS cborMsgEncode cborMsgDecode =
 
     convertCborDecoder
       :: (forall s. CBOR.Decoder s a)
-      -> m (DecodeStep BS.ByteString DeserialiseFailure m a)
+      -> m (DecodeStep BS.ByteString CBOR.DeserialiseFailure m a)
     convertCborDecoder cborDecode = convertCborDecoderBS cborDecode stToIO
 
 convertCborDecoderBS
   :: forall s m a. Functor m
-  => (CBOR.Decoder s a)
+  => CBOR.Decoder s a
+  -- ^ cbor decoder
   -> (forall b. ST s b -> m b)
-  -> m (DecodeStep BS.ByteString DeserialiseFailure m a)
+  -- ^ lift ST computation (e.g. 'Control.Monad.ST.stToIO', 'stToPrim', etc)
+  -> m (DecodeStep BS.ByteString CBOR.DeserialiseFailure m a)
 convertCborDecoderBS cborDecode liftST =
     go <$> liftST (CBOR.deserialiseIncremental cborDecode)
   where
     go :: CBOR.IDecode s a
-       -> DecodeStep BS.ByteString DeserialiseFailure m a
+       -> DecodeStep BS.ByteString CBOR.DeserialiseFailure m a
     go (CBOR.Done  trailing _ x)
       | BS.null trailing       = DecodeDone x Nothing
       | otherwise              = DecodeDone x (Just trailing)
@@ -107,11 +111,13 @@ mkCodecCborLazyBS
              StateTokenI st
           => ActiveState st
           => Message ps st st' -> CBOR.Encoding)
+  -- ^ cbor encoder
 
   -> (forall (st :: ps) s.
              ActiveState st
           => StateToken st
           -> CBOR.Decoder s (SomeMessage st))
+  -- ^ cbor decoder
 
   -> Codec ps CBOR.DeserialiseFailure m LBS.ByteString
 mkCodecCborLazyBS  cborMsgEncode cborMsgDecode =
@@ -134,8 +140,10 @@ mkCodecCborLazyBS  cborMsgEncode cborMsgDecode =
 
 convertCborDecoderLBS
   :: forall s m a. Monad m
-  => (CBOR.Decoder s a)
+  => CBOR.Decoder s a
+  -- ^ cbor decoder
   -> (forall b. ST s b -> m b)
+  -- ^ lift ST computation (e.g. 'Control.Monad.ST.stToIO', 'stToPrim', etc)
   -> m (DecodeStep LBS.ByteString CBOR.DeserialiseFailure m a)
 convertCborDecoderLBS cborDecode liftST =
     go [] =<< liftST (CBOR.deserialiseIncremental cborDecode)
@@ -155,7 +163,7 @@ convertCborDecoderLBS cborDecode liftST =
     -- We keep a bunch of chunks and supply the CBOR decoder with them
     -- until we run out, when we go get another bunch.
     go (c:cs) (CBOR.Partial  k) = go cs =<< liftST (k (Just c))
-    go []     (CBOR.Partial  k) = return $ DecodePartial $ \mbs -> case mbs of
+    go []     (CBOR.Partial  k) = return $ DecodePartial $ \case
                                     Nothing -> go [] =<< liftST (k Nothing)
                                     Just bs -> go cs (CBOR.Partial k)
                                       where cs = LBS.toChunks bs

typed-protocols-examples/src/Network/TypedProtocol/PingPong/Type.hs

@@ -42,12 +42,9 @@ data SPingPong (st :: PingPong) where
 
 deriving instance Show (SPingPong st)
 
-instance StateTokenI StIdle where
-    stateToken = SingIdle
-instance StateTokenI StBusy where
-    stateToken = SingBusy
-instance StateTokenI StDone where
-    stateToken = SingDone
+instance StateTokenI StIdle where stateToken = SingIdle
+instance StateTokenI StBusy where stateToken = SingBusy
+instance StateTokenI StDone where stateToken = SingDone
 
 instance Protocol PingPong where
 

typed-protocols-stateful-cborg/src/Network/TypedProtocol/Stateful/Codec/CBOR.hs

@@ -49,12 +49,14 @@ mkCodecCborStrictBS
              StateTokenI st
           =>ActiveState st
           => f st' -> Message ps st st' -> CBOR.Encoding)
+  -- ^ cbor encoder
 
   -> (forall (st :: ps) s.
              ActiveState st
           => StateToken st
           -> f st
           -> CBOR.Decoder s (SomeMessage st))
+  -- ^ cbor decoder
 
   -> Codec ps DeserialiseFailure f m BS.ByteString
 mkCodecCborStrictBS cborMsgEncode cborMsgDecode =
@@ -90,12 +92,14 @@ mkCodecCborLazyBS
           => ActiveState st
           => f st'
           -> Message ps st st' -> CBOR.Encoding)
+  -- ^ cbor encoder
 
   -> (forall (st :: ps) s.
              ActiveState st
           => StateToken st
           -> f st
           -> CBOR.Decoder s (SomeMessage st))
+  -- ^ cbor decoder
 
   -> Codec ps CBOR.DeserialiseFailure f m LBS.ByteString
 mkCodecCborLazyBS cborMsgEncode cborMsgDecode =

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Codec.hs

@@ -24,16 +24,23 @@ module Network.TypedProtocol.Stateful.Codec
   , isoCodec
   , mapFailureCodec
   , liftCodec
-    -- ** Related types
-  , ActiveState
-  , PeerRole (..)
-  , SomeMessage (..)
-  , CodecFailure (..)
     -- ** Incremental decoding
   , DecodeStep (..)
   , runDecoder
   , runDecoderPure
-    -- ** Codec properties
+    -- ** Related types
+    -- *** SomeMessage
+  , SomeMessage (..)
+    -- *** StateToken 
+  , StateToken
+  , StateTokenI (..)
+    -- *** ActiveState
+  , ActiveState
+    -- *** PeerRole
+  , PeerRole (..)
+    -- * CodecFailure
+  , CodecFailure (..)
+    -- * Testing codec properties
   , AnyMessage (..)
   , pattern AnyMessageAndAgency
   , prop_codecM
@@ -42,9 +49,6 @@ module Network.TypedProtocol.Stateful.Codec
   , prop_codec_splits
   , prop_codecs_compatM
   , prop_codecs_compat
-    -- ** StateToken 
-  , StateToken
-  , StateTokenI (..)
   ) where
 
 import           Data.Kind (Type)

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Driver.hs

@@ -13,12 +13,13 @@
 -- imported qualified.
 --
 module Network.TypedProtocol.Stateful.Driver
-  ( -- * Running a peer
-    runPeerWithDriver
+  ( -- * DriverIngerface
+    Driver (..)
+    -- * Running a peer
+  , runPeerWithDriver
     -- * Re-exports
-  , DecodeStep (..)
-  , Driver (..)
   , SomeMessage (..)
+  , DecodeStep (..)
   ) where
 
 import Control.Monad.Class.MonadSTM
@@ -46,12 +47,6 @@ data Driver ps (pr :: PeerRole) bytes failure dstate f m =
 
         , -- | Receive a message, a blocking action which reads from the network
           -- and runs the incremental decoder until a full message is decoded.
-          -- As an input it might receive a 'DecodeStep' previously started with
-          -- 'tryRecvMessage'.
-          --
-          -- It could be implemented in terms of 'recvMessageSTM', but in some
-          -- cases it can be easier (or more performant) to have a different
-          -- implementation.
           --
           recvMessage   :: forall (st :: ps).
                            StateTokenI st

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Peer.hs

@@ -46,8 +46,8 @@ import Network.TypedProtocol.Core as Core
 --
 -- For example:
 --
--- > pingPongClientExample :: Int -> Peer PingPong AsClient StIdle m ()
--- > pingPongServerExample ::        Peer PingPong AsServer StIdle m Int
+-- > pingPongClientExample :: Peer PingPong AsClient StIdle m ()
+-- > pingPongServerExample :: Peer PingPong AsServer StIdle m Int
 --
 -- The actions that a peer can take are:
 --

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Peer/Client.hs

@@ -12,7 +12,8 @@
 -- singleton.
 --
 module Network.TypedProtocol.Stateful.Peer.Client
-  ( Client
+  ( -- * Client type alias and its pattern synonyms
+    Client
   , pattern Effect
   , pattern Yield
   , pattern Await

typed-protocols-stateful/src/Network/TypedProtocol/Stateful/Peer/Server.hs

@@ -12,7 +12,8 @@
 -- singleton.
 --
 module Network.TypedProtocol.Stateful.Peer.Server
-  ( Server
+  ( -- * Server type alias and its pattern synonyms
+    Server
   , pattern Effect
   , pattern Yield
   , pattern Await

typed-protocols/src/Network/TypedProtocol.hs

@@ -8,7 +8,6 @@ module Network.TypedProtocol
     -- * Defining and implementing protocols
     -- $defining
     module Network.TypedProtocol.Core
-  , module Network.TypedProtocol.Peer
     -- ** Protocol proofs and tests
     -- $tests
   , module Network.TypedProtocol.Proofs
@@ -19,7 +18,6 @@ module Network.TypedProtocol
 
 import           Network.TypedProtocol.Core
 import           Network.TypedProtocol.Driver
-import           Network.TypedProtocol.Peer
 import           Network.TypedProtocol.Proofs