From 43b3b1eab1ef270c46718d003a75593477801f5f Mon Sep 17 00:00:00 2001
From: Sam T <sta.cs.vsu@gmail.com>
Date: Sat, 13 Apr 2013 11:26:27 +0400
Subject: + add docs

---
 src/Data/Torrent.hs | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 4 deletions(-)

(limited to 'src/Data')

diff --git a/src/Data/Torrent.hs b/src/Data/Torrent.hs
index 57831acf..83f4094c 100644
--- a/src/Data/Torrent.hs
+++ b/src/Data/Torrent.hs
@@ -20,44 +20,113 @@ import Network.URI
 
 type Time = Text
 
--- TODO comment fields
 -- TODO more convenient form of torrent info.
+-- | Metainfo about particular torrent.
 data Torrent = Torrent {
       tInfoHash     :: InfoHash
+      -- ^ SHA1 hash of the 'TorrentInfo' of the 'Torrent'.
+
     , tAnnounce     ::       URI
+      -- ^ The URL of the tracker.
+
     , tAnnounceList :: Maybe [[URI]]
+      -- ^ Announce list add multiple tracker support.
+      --
+      --   BEP 12: http://www.bittorrent.org/beps/bep_0012.html
+
     , tComment      :: Maybe Text
+      -- ^ Free-form comments of the author.
+
     , tCreatedBy    :: Maybe ByteString
+      -- ^ Name and version of the program used to create the .torrent.
+
     , tCreationDate :: Maybe Time
+      -- ^ Creation time of the torrent, in standard UNIX epoch.
+
     , tEncoding     :: Maybe ByteString
+      -- ^ String encoding format used to generate the pieces part of
+      --   the info dictionary in the .torrent metafile.
+
+      -- ^ Info about each content file.
     , tInfo         :: TorrentInfo
+
+
     , tPublisher    :: Maybe URI
+      -- ^ Containing the RSA public key of the publisher of the torrent.
+      --   Private counterpart of this key that has the authority to allow
+      --   new peers onto the swarm.
+
     , tPublisherURL :: Maybe URI
+    , tSignature    :: Maybe ByteString
+      -- ^ The RSA signature of the info dictionary (specifically,
+      --   the encrypted SHA-1 hash of the info dictionary).
     } deriving Show
 
+-- | Info part of the .torrent file contain info about each content file.
 data TorrentInfo =
     SingleFile {
       tLength       :: Int
+      -- ^ Length of the file in bytes.
+
     , tMD5sum       :: Maybe ByteString
+      -- | 32 character long MD5 sum of the file.
+      --   Used by third-party tools, not by bittorrent protocol itself.
+
     , tName         :: ByteString
+      -- ^ Suggested name of the file single file.
+
+
 
     , tPieceLength  :: Int
-    , tPieces       :: ByteString -- Vector ByteString?
+      -- ^ Number of bytes in each piece.
+
+    , tPieces       :: ByteString
+      -- ^ Concatenation of all 20-byte SHA1 hash values.
+
     , tPrivate      :: Maybe Bool
+      -- ^ If set the client MUST publish its presence to get other peers ONLY
+      --   via the trackers explicity described in the metainfo file.
+      --
+      --   BEP 27: http://www.bittorrent.org/beps/bep_0027.html
     }
+
   | MultiFile {
       tFiles        :: [TorrentFile]
+      -- ^ List of the all files that torrent contains.
+
     , tName         :: ByteString
+      -- | The file path of the directory in which to store all the files.
+
+
 
     , tPieceLength  :: Int
-    , tPieces       :: ByteString -- Vector ByteString?
+
+      -- ^ Number of bytes in each piece.
+    , tPieces       :: ByteString
+      -- ^ Concatenation of all 20-byte SHA1 hash values.
+
     , tPrivate      :: Maybe Bool
+      -- ^ If set the client MUST publish its presence to get other peers ONLY
+      --   via the trackers explicity described in the metainfo file,
+      --
+      --   BEP 27: http://www.bittorrent.org/beps/bep_0027.html
     } deriving (Show, Read, Eq)
 
+-- | Contain info about one single file.
 data TorrentFile = TorrentFile {
       tfLength      :: Int
+      -- ^ Length of the file in bytes.
+
     , tfMD5sum      :: Maybe ByteString
+      -- | 32 character long MD5 sum of the file.
+      --   Used by third-party tools, not by bittorrent protocol itself.
+
     , tfPath        :: [ByteString]
+      -- ^ One or more string elements that together represent the path and
+      --   filename. Each element in the list corresponds to either a directory
+      --   name or (in the case of the last element) the filename.
+      --   For example, the file "dir1/dir2/file.ext" would consist of three
+      --   string elements ["dir1", "dir2", "file.ext"]
     } deriving (Show, Read, Eq)
 
 instance BEncodable URI where
@@ -79,10 +148,11 @@ instance BEncodable Torrent where
     , "info"          -->  tInfo t
     , "publisher"     -->? tPublisher t
     , "publisher-url" -->? tPublisherURL t
+    , "signature"     -->? tSignature t
     ]
 
   fromBEncode (BDict d) | Just info <- M.lookup "info" d =
-    Torrent <$> pure (hashlazy (encode info))
+    Torrent <$> pure (hashlazy (encode info)) -- WARN
             <*> d >--  "announce"
             <*> d >--? "announce-list"
             <*> d >--? "comment"
@@ -92,6 +162,7 @@ instance BEncodable Torrent where
             <*> d >--  "info"
             <*> d >--? "publisher"
             <*> d >--? "publisher-url"
+            <*> d >--? "singature"
 
   fromBEncode _ = decodingError "Torrent"
 
-- 
cgit v1.2.3