Comments

client.go

@@ -1975,6 +1975,7 @@ func (t Torrent) Files() (ret []File) {
 	return
 }
 
+// Marks the pieces in the given region for download.
 func (t Torrent) SetRegionPriority(off, len int64) {
 	t.cl.mu.Lock()
 	defer t.cl.mu.Unlock()

connection.go

@@ -39,7 +39,8 @@ type connection struct {
 	post      chan pp.Message
 	writeCh   chan []byte
 
-	// The connections preferred order to download pieces.
+	// The connection's preferred order to download pieces. The index is the
+	// piece, the value is its priority.
 	piecePriorities []int
 	// The piece request order based on piece priorities.
 	pieceRequestOrder *pieceordering.Instance
@@ -109,6 +110,7 @@ func (cn *connection) pendPiece(piece int, priority piecePriority) {
 	// Priority regions not to scale. Within each region, piece is randomized
 	// according to connection.
 
+	// <-request first -- last->
 	// [ Now         ]
 	//  [ Next       ]
 	//   [ Readahead ]

internal/pieceordering/pieceordering.go

@@ -10,7 +10,11 @@ import (
 
 // Maintains piece integers by their ascending assigned keys.
 type Instance struct {
-	sl        *skiplist.SkipList
+	// Contains the ascending priority keys. The keys contain a slice of piece
+	// indices.
+	sl *skiplist.SkipList
+	// Maps from piece index back to its key, so that it can be remove
+	// efficiently from the skip list.
 	pieceKeys map[int]int
 }
 
@@ -41,6 +45,7 @@ func (me *Instance) SetPiece(piece, key int) {
 	me.shuffleItem(key)
 }
 
+// Shuffle the piece indices that share a given key.
 func (me *Instance) shuffleItem(key int) {
 	_item, ok := me.sl.Get(key)
 	if !ok {

piece.go

@@ -7,6 +7,8 @@ import (
 	pp "github.com/anacrolix/torrent/peer_protocol"
 )
 
+// Piece priority describes the importance of obtaining a particular piece.
+
 type piecePriority byte
 
 const (
@@ -18,8 +20,8 @@ const (
 )
 
 type piece struct {
-	Hash pieceSum
+	Hash pieceSum // The completed piece SHA1 hash, from the metainfo "pieces" field.
-	// Chunks we don't have. The offset and length can be determined by our
+	// Chunks we don't have. The offset and length can be determined by the
 	// request chunkSize in use.
 	PendingChunkSpecs []bool
 	Hashing           bool