Docs and comments

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{}

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

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.
+}

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)

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,