More public interface tidying

diff --git a/client.go b/client.go
index 28a9ce43052300f1c93964cf7e53351fc930b3cd..4a4c8322fca1b44fdd55f7081e1af1deab7d7de6 100644 (file)
--- a/client.go
+++ b/client.go
@@ -41,6 +41,9 @@ import (
 
        "github.com/anacrolix/torrent/mse"
 
+       "github.com/anacrolix/libtorgo/bencode"
+       "github.com/anacrolix/libtorgo/metainfo"
+       "github.com/anacrolix/sync"
        "github.com/anacrolix/torrent/data"
        filePkg "github.com/anacrolix/torrent/data/file"
        "github.com/anacrolix/torrent/dht"
@@ -51,10 +54,7 @@ import (
        "github.com/anacrolix/torrent/tracker"
        _ "github.com/anacrolix/torrent/tracker/udp"
        . "github.com/anacrolix/torrent/util"
-       "github.com/anacrolix/sync"
        "github.com/anacrolix/utp"
-       "github.com/anacrolix/libtorgo/bencode"
-       "github.com/anacrolix/libtorgo/metainfo"
 )
 
 var (
@@ -267,7 +267,7 @@ func (cl *Client) torrentReadAt(t *torrent, off int64, p []byte) (n int, err err
                return
        }
        pieceOff := pp.Integer(off % int64(t.usualPieceSize()))
-       pieceLeft := int(t.PieceLength(index) - pieceOff)
+       pieceLeft := int(t.pieceLength(index) - pieceOff)
        if pieceLeft <= 0 {
                err = io.EOF
                return
@@ -1506,7 +1506,7 @@ func (me *Client) connectionLoop(t *torrent, c *connection) error {
                        // routine.
                        // c.PeerRequests[request] = struct{}{}
                        p := make([]byte, msg.Length)
-                       n, err := dataReadAt(t.data, p, int64(t.PieceLength(0))*int64(msg.Index)+int64(msg.Begin))
+                       n, err := dataReadAt(t.data, p, int64(t.pieceLength(0))*int64(msg.Index)+int64(msg.Begin))
                        if err != nil {
                                return fmt.Errorf("reading t data to serve request %q: %s", request, err)
                        }
@@ -2213,7 +2213,8 @@ func (cl *Client) torrentCacheMetaInfo(ih InfoHash) (mi *metainfo.MetaInfo, err
        return
 }
 
-// For adding new torrents to a client.
+// Specifies a new torrent for adding to a client. There are helpers for
+// magnet URIs and torrent metainfo files.
 type TorrentSpec struct {
        Trackers    [][]string
        InfoHash    InfoHash

diff --git a/misc.go b/misc.go
index 70d8375e42262fbdb6be87d585232f2f868f8952..873d73adfc0a6f580bf5b7648364113ff31f2e3c 100644 (file)
--- a/misc.go
+++ b/misc.go
@@ -104,13 +104,13 @@ func metadataPieceSize(totalSize int, piece int) int {
        return ret
 }
 
-type Super interface {
+type superer interface {
        Super() interface{}
 }
 
 // Returns ok if there's a parent, and it's not nil.
 func super(child interface{}) (parent interface{}, ok bool) {
-       s, ok := child.(Super)
+       s, ok := child.(superer)
        if !ok {
                return
        }

diff --git a/torrent.go b/torrent.go
index 776c2cf37da373c3dd6e4e1cbb37c221230310eb..b2eebdcadceba87932de4c57892ec1eab9abecea 100644 (file)
--- a/torrent.go
+++ b/torrent.go
@@ -14,12 +14,12 @@ import (
 
        "github.com/bradfitz/iter"
 
+       "github.com/anacrolix/libtorgo/bencode"
+       "github.com/anacrolix/libtorgo/metainfo"
        "github.com/anacrolix/torrent/data"
        pp "github.com/anacrolix/torrent/peer_protocol"
        "github.com/anacrolix/torrent/tracker"
        "github.com/anacrolix/torrent/util"
-       "github.com/anacrolix/libtorgo/bencode"
-       "github.com/anacrolix/libtorgo/metainfo"
 )
 
 func (t *torrent) pieceNumPendingBytes(index int) (count pp.Integer) {
@@ -28,11 +28,11 @@ func (t *torrent) pieceNumPendingBytes(index int) (count pp.Integer) {
        }
        piece := t.Pieces[index]
        if !piece.EverHashed {
-               return t.PieceLength(index)
+               return t.pieceLength(index)
        }
        pendingChunks := t.Pieces[index].PendingChunkSpecs
        count = pp.Integer(len(pendingChunks)) * chunkSize
-       _lastChunkSpec := lastChunkSpec(t.PieceLength(index))
+       _lastChunkSpec := lastChunkSpec(t.pieceLength(index))
        if _lastChunkSpec.Length != chunkSize {
                if _, ok := pendingChunks[_lastChunkSpec]; ok {
                        count += _lastChunkSpec.Length - chunkSize
@@ -423,10 +423,14 @@ func (t *torrent) newMetadataExtensionMessage(c *connection, msgType int, piece
 }
 
 type PieceStatusCharSequence struct {
-       Char  byte
-       Count int
+       Char  byte // The state of this sequence of pieces.
+       Count int  // How many consecutive pieces have this state.
 }
 
+// Returns the state of pieces of the torrent. They are grouped into runs of
+// same state. The sum of the Counts of the sequences is the number of pieces
+// in the torrent. See the function torrent.pieceStatusChar for the possible
+// states.
 func (t *torrent) PieceStatusCharSequences() []PieceStatusCharSequence {
        t.stateMu.Lock()
        defer t.stateMu.Unlock()
@@ -549,7 +553,7 @@ func (t *torrent) bytesLeft() (left int64) {
 }
 
 func (t *torrent) piecePartiallyDownloaded(index int) bool {
-       return t.pieceNumPendingBytes(index) != t.PieceLength(index)
+       return t.pieceNumPendingBytes(index) != t.pieceLength(index)
 }
 
 func numChunksForPiece(chunkSize int, pieceSize int) int {
@@ -561,7 +565,7 @@ func (t *torrent) usualPieceSize() int {
 }
 
 func (t *torrent) lastPieceSize() int {
-       return int(t.PieceLength(t.numPieces() - 1))
+       return int(t.pieceLength(t.numPieces() - 1))
 }
 
 func (t *torrent) numPieces() int {
@@ -653,9 +657,9 @@ func (t *torrent) bitfield() (bf []bool) {
 }
 
 func (t *torrent) pieceChunks(piece int) (css []chunkSpec) {
-       css = make([]chunkSpec, 0, (t.PieceLength(piece)+chunkSize-1)/chunkSize)
+       css = make([]chunkSpec, 0, (t.pieceLength(piece)+chunkSize-1)/chunkSize)
        var cs chunkSpec
-       for left := t.PieceLength(piece); left != 0; left -= cs.Length {
+       for left := t.pieceLength(piece); left != 0; left -= cs.Length {
                cs.Length = left
                if cs.Length > chunkSize {
                        cs.Length = chunkSize
@@ -671,7 +675,7 @@ func (t *torrent) pendAllChunkSpecs(index int) {
        if piece.PendingChunkSpecs == nil {
                piece.PendingChunkSpecs = make(
                        map[chunkSpec]struct{},
-                       (t.PieceLength(index)+chunkSize-1)/chunkSize)
+                       (t.pieceLength(index)+chunkSize-1)/chunkSize)
        }
        pcss := piece.PendingChunkSpecs
        for _, cs := range t.pieceChunks(int(index)) {
@@ -689,7 +693,7 @@ type Peer struct {
        SupportsEncryption bool
 }
 
-func (t *torrent) PieceLength(piece int) (len_ pp.Integer) {
+func (t *torrent) pieceLength(piece int) (len_ pp.Integer) {
        if int(piece) == t.numPieces()-1 {
                len_ = pp.Integer(t.Length() % t.Info.PieceLength)
        }