From 71faf0f5b46b95aa063b00d510097f2672c645d7 Mon Sep 17 00:00:00 2001 From: Sam Truzjan Date: Mon, 16 Dec 2013 19:17:05 +0400 Subject: Fix documentation markup --- src/Data/BEncode.hs | 84 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 36 deletions(-) diff --git a/src/Data/BEncode.hs b/src/Data/BEncode.hs index a866a6e..2494166 100644 --- a/src/Data/BEncode.hs +++ b/src/Data/BEncode.hs @@ -17,7 +17,7 @@ -- -- * lists - represented as ordinary lists; -- --- * dictionaries — represented as 'Map'; +-- * dictionaries — represented as 'BDictMap'; -- -- To serialize any other types we need to make conversion. To -- make conversion more convenient there is type class for it: @@ -40,7 +40,9 @@ -- > ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" -- -- --- This module is considered to be imported qualified. +-- This module is considered to be imported qualified, for example: +-- +-- > import Data.BEncode as BE -- {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE Trustworthy #-} @@ -125,7 +127,7 @@ type Result = Either String -- the following datatype: -- -- > data List a = C { _head :: a --- > , __tail :: List a } +-- > , __tail :: List a } -- > | N -- > deriving Generic -- @@ -140,7 +142,8 @@ type Result = Either String -- > > toBEncode (C 123 $ C 1 N) -- > BDict (fromList [("head",BInteger 123),("tail",BList [])]) -- --- Note that '_' prefixes are omitted since they are used for lens. +-- Note that prefixed underscore characters are omitted since they +-- are usually used for lens. -- class BEncode a where -- | See an example of implementation here 'Assoc' @@ -559,28 +562,34 @@ instance (BEncode a, BEncode b, BEncode c, BEncode d, BEncode e) -- optional keys. Suppose we have we following datatype we want to -- serialize: -- --- > data FileInfo = FileInfo --- > { fileLength :: Integer --- > , fileMD5sum :: Maybe ByteString --- > , filePath :: [ByteString] --- > , fileTags :: Maybe [Text] --- > } deriving (Show, Read, Eq) +-- @ +-- data FileInfo = FileInfo +-- { fileLength :: Integer +-- , fileMD5sum :: Maybe ByteString +-- , filePath :: [ByteString] +-- , fileTags :: Maybe [Text] +-- } deriving (Show, Read, Eq) +-- @ -- --- We need to make /instance BEncode FileInfo/, though we don't want --- to check the both /maybes/ manually. The more declarative and +-- We need to make @instance 'BEncode' FileInfo@, though we don't want +-- to check the both 'Maybe's manually. The more declarative and -- convenient way to define the 'toBEncode' method is to use -- dictionary builders: -- --- > instance BEncode FileInfo where --- > toBEncode FileInfo {..} = toDict $ --- > "length" .=! fileLength --- > .: "md5sum" .=? fileMD5sum --- > .: "path" .=! filePath --- > .: "tags" .=? fileTags --- > .: endDict +-- @ +-- instance 'BEncode' FileInfo where +-- 'toBEncode' FileInfo {..} = 'toDict' $ +-- \"length\" '.=!' fileLength +-- '.:' \"md5sum\" '.=?' fileMD5sum +-- '.:' \"path\" '.=!' filePath +-- '.:' \"tags\" '.=?' fileTags +-- '.:' 'endDict' +-- @ +-- +-- NOTE: the list of pairs MUST be sorted lexicographically by keys, +-- like so: -- --- NOTE: the list of pairs SHOULD be sorted lexicographically by --- keys, so: "length" < "md5sum" < "path" < "tags". +-- \"length\" '<' \"md5sum\" '<' \"path\" '<' \"tags\" -- data Assoc = Some !BKey BValue | None @@ -592,8 +601,8 @@ data Assoc = Some !BKey BValue infix 6 .=! --- | Like (.=!) but if the value is not present then the key do not --- appear in resulting bencode dictionary. +-- | Like the ('.=!') operator but if the value is not present then +-- the key do not appear in resulting bencode dictionary. -- (.=?) :: BEncode a => BKey -> Maybe a -> Assoc _ .=? Nothing = None @@ -629,18 +638,21 @@ endDict = Nil -- declarative style. Using the same /FileInfo/ datatype the -- 'fromBEncode' function instance looks like: -- --- > instance BEncodable FileInfo where --- > fromBEncode = fromDict $ do --- > FileInfo <$>! "length" --- > <*>? "md5sum" --- > <*>! "path" --- > <*>? "tags" +-- @ +-- instance 'BEncode' FileInfo where +-- 'fromBEncode' = 'fromDict' $ do +-- FileInfo '<$>!' \"length\" +-- '<*>?' \"md5sum\" +-- '<*>!' \"path\" +-- '<*>?' \"tags\" +-- @ -- -- The /reqKey/ is used to extract required key — if lookup is failed -- then whole destructuring fail. -- --- NOTE: the actions SHOULD be sorted lexicographically by keys, so: --- "length" < "md5sum" < "path" < "tags". +-- NOTE: the actions MUST be sorted lexicographically by keys, like so: +-- +-- \"length\" '<' \"md5sum\" '<' \"path\" '<' \"tags\" -- newtype Get a = Get { runGet :: StateT BDict Result a } deriving (Functor, Applicative, Alternative) @@ -692,35 +704,35 @@ field m = Get $ do v <- runGet m either throwError pure $ fromBEncode v --- | Shorthand for /f <$> field (req k)/. +-- | Shorthand for: @f '<$>' 'field' ('req' k)@. (<$>!) :: BEncode a => (a -> b) -> BKey -> Get b f <$>! k = f <$> field (req k) {-# INLINE (<$>!) #-} infixl 4 <$>! --- | Shorthand for /f <$> optional (field (req k))/. +-- | Shorthand for: @f '<$>' 'optional' ('field' ('req' k))@. (<$>?) :: BEncode a => (Maybe a -> b) -> BKey -> Get b f <$>? k = f <$> optional (field (req k)) {-# INLINE (<$>?) #-} infixl 4 <$>? --- | Shorthand for /f <*> field (req k)/. +-- | Shorthand for: @f '<*>' 'field' ('req' k)@. (<*>!) :: BEncode a => Get (a -> b) -> BKey -> Get b f <*>! k = f <*> field (req k) {-# INLINE (<*>!) #-} infixl 4 <*>! --- | Shorthand for /f <*> optional (field (req k))/. +-- | Shorthand for: @f '<*>' 'optional' ('field' ('req' k))@. (<*>?) :: BEncode a => Get (Maybe a -> b) -> BKey -> Get b f <*>? k = f <*> optional (field (req k)) {-# INLINE (<*>?) #-} infixl 4 <*>? --- | Run a 'Get' monad. +-- | Run a 'Get' monad. See 'Get' for usage. fromDict :: forall a. Typeable a => Get a -> BValue -> Result a fromDict m (BDict d) = evalStateT (runGet m) d fromDict _ _ = decodingError (show (typeOf inst)) -- cgit v1.2.3