From 7e8ee950bc3c10091e52811ec5b8bbff9c879d11 Mon Sep 17 00:00:00 2001
From: Matt Joiner <anacrolix@gmail.com>
Date: Wed, 3 Jun 2015 13:30:55 +1000
Subject: [PATCH] Docs and comments

---
 client.go       |  4 +++-
 doc.go          | 17 ++++++++++++++++-
 example_test.go | 14 +++++++++++++-
 reader.go       |  3 +++
 t.go            |  3 +++
 5 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/client.go b/client.go
index 9f7051a5..b21fb522 100644
--- 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 d6b42e78..e7cc1106 100644
--- 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 02655e95..c03fcdd2 100644
--- 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 3cdae00a..99b0432e 100644
--- 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 2f0ddbee..c0132d77 100644
--- 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,