From: Matt Joiner <anacrolix@gmail.com>
Date: Thu, 19 Mar 2015 23:52:01 +0000 (+1100)
Subject: More cleaning up of public interface
X-Git-Tag: v1.0.0~1262
X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=0c63952353f58bc14dcece56fd07894640fed3d9;p=btrtrc.git

More cleaning up of public interface
---

diff --git a/client.go b/client.go
index b1e66ad7..2bca18fb 100644
--- a/client.go
+++ b/client.go
@@ -247,7 +247,7 @@ func (cl *Client) WriteStatus(_w io.Writer) {
 			w.WriteString("<missing metainfo>")
 		}
 		fmt.Fprint(w, "\n")
-		t.WriteStatus(w)
+		t.writeStatus(w)
 		fmt.Fprintln(w)
 	}
 }
@@ -480,6 +480,7 @@ func (cl *Client) initBannedTorrents() error {
 	return nil
 }
 
+// Creates a new client. Clients contain zero or more Torrents.
 func NewClient(cfg *Config) (cl *Client, err error) {
 	if cfg == nil {
 		cfg = &Config{}
@@ -684,6 +685,7 @@ func (cl *Client) incomingConnection(nc net.Conn, utp bool) {
 	}
 }
 
+// Returns a handle to the given torrent, if it's present in the client.
 func (cl *Client) Torrent(ih InfoHash) (T Torrent, ok bool) {
 	cl.mu.Lock()
 	defer cl.mu.Unlock()
@@ -1396,7 +1398,7 @@ func (cl *Client) gotMetadataExtensionMsg(payload []byte, t *torrent, c *connect
 			log.Printf("got bad metadata piece")
 			break
 		}
-		t.SaveMetadataPiece(piece, payload[begin:])
+		t.saveMetadataPiece(piece, payload[begin:])
 		c.UsefulChunksReceived++
 		c.lastUsefulChunkReceived = time.Now()
 		if !t.haveAllMetadataPieces() {
@@ -1614,7 +1616,7 @@ func (me *Client) connectionLoop(t *torrent, c *connection) error {
 					if !ok {
 						log.Printf("bad metadata_size type: %T", metadata_sizeUntyped)
 					} else {
-						t.SetMetadataSize(metadata_size)
+						t.setMetadataSize(metadata_size)
 					}
 				}
 				if _, ok := c.PeerExtensionIDs["ut_metadata"]; ok {
@@ -1979,6 +1981,7 @@ func (t *torrent) addTrackers(announceList [][]string) {
 	t.Trackers = newTrackers
 }
 
+// A handle to a live torrent within a Client.
 type Torrent struct {
 	cl *Client
 	*torrent
@@ -1994,6 +1997,7 @@ func (t Torrent) Drop() {
 	t.cl.mu.Unlock()
 }
 
+// Provides access to regions of torrent data that correspond to its files.
 type File struct {
 	t      Torrent
 	path   string
@@ -2158,10 +2162,6 @@ func (t Torrent) SetRegionPriority(off, len int64) {
 	}
 }
 
-func (t Torrent) MetainfoFilepath() string {
-	return filepath.Join(t.cl.ConfigDir(), "torrents", t.InfoHash.HexString()+".torrent")
-}
-
 func (t Torrent) AddPeers(pp []Peer) error {
 	cl := t.cl
 	cl.mu.Lock()
@@ -2170,17 +2170,17 @@ func (t Torrent) AddPeers(pp []Peer) error {
 	return nil
 }
 
+// Marks the entire torrent for download.
 func (t Torrent) DownloadAll() {
 	t.cl.mu.Lock()
-	for i := 0; i < t.numPieces(); i++ {
-		// TODO: Leave higher priorities as they were?
-		t.cl.prioritizePiece(t.torrent, i, piecePriorityNormal)
+	defer t.cl.mu.Unlock()
+	for i := range iter.N(t.numPieces()) {
+		t.cl.raisePiecePriority(t.torrent, i, piecePriorityNormal)
 	}
-	// Nice to have the first and last pieces soon for various interactive
+	// Nice to have the first and last pieces sooner for various interactive
 	// purposes.
-	t.cl.prioritizePiece(t.torrent, 0, piecePriorityReadahead)
-	t.cl.prioritizePiece(t.torrent, t.numPieces()-1, piecePriorityReadahead)
-	t.cl.mu.Unlock()
+	t.cl.raisePiecePriority(t.torrent, 0, piecePriorityReadahead)
+	t.cl.raisePiecePriority(t.torrent, t.numPieces()-1, piecePriorityReadahead)
 }
 
 func (me Torrent) ReadAt(p []byte, off int64) (n int, err error) {
diff --git a/torrent.go b/torrent.go
index 31366c03..5ee3376a 100644
--- a/torrent.go
+++ b/torrent.go
@@ -22,7 +22,7 @@ import (
 	"github.com/anacrolix/libtorgo/metainfo"
 )
 
-func (t *torrent) PieceNumPendingBytes(index int) (count pp.Integer) {
+func (t *torrent) pieceNumPendingBytes(index int) (count pp.Integer) {
 	if t.pieceComplete(index) {
 		return 0
 	}
@@ -251,7 +251,7 @@ func (t *torrent) invalidateMetadata() {
 	t.Info = nil
 }
 
-func (t *torrent) SaveMetadataPiece(index int, data []byte) {
+func (t *torrent) saveMetadataPiece(index int, data []byte) {
 	if t.haveInfo() {
 		return
 	}
@@ -342,7 +342,7 @@ func (t *torrent) haveAllMetadataPieces() bool {
 	return true
 }
 
-func (t *torrent) SetMetadataSize(bytes int64) {
+func (t *torrent) setMetadataSize(bytes int64) {
 	if t.MetaData != nil {
 		return
 	}
@@ -461,7 +461,7 @@ func (t *torrent) pieceStatusCharSequences() (ret []PieceStatusCharSequence) {
 	return
 }
 
-func (t *torrent) WriteStatus(w io.Writer) {
+func (t *torrent) writeStatus(w io.Writer) {
 	fmt.Fprintf(w, "Infohash: %x\n", t.InfoHash)
 	fmt.Fprintf(w, "Piece length: %s\n", func() string {
 		if t.haveInfo() {
@@ -520,6 +520,8 @@ func (t *torrent) announceList() (al [][]string) {
 	return
 }
 
+// Returns a run-time generated MetaInfo that includes the info bytes and
+// announce-list as currently known to the client.
 func (t *torrent) MetaInfo() *metainfo.MetaInfo {
 	if t.MetaData == nil {
 		panic("info bytes not set")
@@ -541,13 +543,13 @@ func (t *torrent) bytesLeft() (left int64) {
 		return -1
 	}
 	for i := 0; i < t.numPieces(); i++ {
-		left += int64(t.PieceNumPendingBytes(i))
+		left += int64(t.pieceNumPendingBytes(i))
 	}
 	return
 }
 
 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 {