Docs and comments

diff --git a/client.go b/client.go
index 9f7051a5c29963e0980a5c707ac64b91094d31e1..b21fb5223f6a04b49af191d3a1a6446b1c1f33aa 100644 (file)
--- a/client.go
+++ b/client.go
@@ -114,6 +114,8 @@ func (cl *Client) queueFirstHash(t *torrent, piece int) {
        cl.queuePieceCheck(t, pp.Integer(piece))
 }
 
+// Clients contain zero or more Torrents. A client manages a blocklist, the
+// TCP/UDP protocol ports, and DHT as desired.
 type Client struct {
        halfOpenLimit  int
        peerID         [20]byte
@@ -434,7 +436,7 @@ func (cl *Client) initBannedTorrents() error {
        return nil
 }
 
-// Creates a new client. Clients contain zero or more Torrents.
+// Creates a new client.
 func NewClient(cfg *Config) (cl *Client, err error) {
        if cfg == nil {
                cfg = &Config{}

diff --git a/doc.go b/doc.go
index d6b42e789bdea7f913dd8396abaf8d1835e0f099..e7cc110687931505166bccbc55516ce251034fa2 100644 (file)
--- a/doc.go
+++ b/doc.go
@@ -1,3 +1,18 @@
-// Package torrent implements a torrent client.
+/*
+Package torrent implements a torrent client. Goals include:
+ * Configurable data storage, such as file, mmap, and piece-based.
+ * Downloading on demand: torrent.Reader will request only the data required to
+   satisfy Reads, which is ideal for streaming and torrentfs.
 
+BitTorrent features implemented include:
+ * Protocol obfuscation
+ * DHT
+ * uTP
+ * PEX
+ * Magnet
+ * IP Blocklists
+ * Some IPv6
+ * UDP Trackers
+
+*/
 package torrent

diff --git a/example_test.go b/example_test.go
index 02655e9596aa7e3ee8da2f3285fd7ea4182205dd..c03fcdd22d9554997cb9430f60c6d712b28afd21 100644 (file)
--- a/example_test.go
+++ b/example_test.go
@@ -1,13 +1,14 @@
 package torrent_test
 
 import (
+       "io"
        "log"
 
        "github.com/anacrolix/torrent"
 )
 
 func Example() {
-       c, _ := torrent.NewClient(&torrent.Config{})
+       c, _ := torrent.NewClient(nil)
        defer c.Close()
        t, _ := c.AddMagnet("magnet:?xt=urn:btih:ZOCMZQIPFFW7OLLMIC5HUB6BPCSDEOQU")
        <-t.GotInfo()
@@ -15,3 +16,14 @@ func Example() {
        c.WaitAll()
        log.Print("ermahgerd, torrent downloaded")
 }
+
+func Example_fileReader() {
+       var (
+               t torrent.Torrent
+               f torrent.File
+       )
+       r := t.NewReader()
+       defer r.Close()
+       fr := io.NewSectionReader(r, f.Offset(), f.Length())
+       // fr will read from the parts of the torrent pertaining to f.
+}

diff --git a/reader.go b/reader.go
index 3cdae00a010efb1995666d9f4b18f1abb43ce073..99b0432e1df2f48f2c40bb157e9951dbe1d7557b 100644 (file)
--- a/reader.go
+++ b/reader.go
@@ -22,6 +22,8 @@ func (r *Reader) SetResponsive() {
        r.responsive = true
 }
 
+// Configure the number of bytes ahead of a read that should also be
+// prioritized in preparation for further reads.
 func (r *Reader) SetReadahead(readahead int64) {
        r.readahead = readahead
 }
@@ -83,6 +85,7 @@ func (r *Reader) Read(b []byte) (n int, err error) {
        return
 }
 
+// Must only return EOF at the end of the torrent.
 func (r *Reader) readAt(b []byte, pos int64) (n int, err error) {
        // defer func() {
        //      log.Println(pos, n, err)

diff --git a/t.go b/t.go
index 2f0ddbee230c11da7bc2fd3efe42d475272bdbdf..c0132d773cdbadefaebbfd5f9b2d752f50f21abe 100644 (file)
--- a/t.go
+++ b/t.go
@@ -23,6 +23,9 @@ func (t *Torrent) Info() *metainfo.Info {
        return t.torrent.Info
 }
 
+// Returns a Reader bound to the torrent's data. All read calls block until
+// the data requested is actually available. Priorities are set to ensure the
+// data requested will be downloaded as soon as possible.
 func (t *Torrent) NewReader() (ret *Reader) {
        ret = &Reader{
                t:         t,