update docs all around

backend/noop/driver.go

@@ -51,6 +51,7 @@ func (n *NoOp) LoadAllUsers(ids []uint64) ([]*models.User, error) {
 	return nil, nil
 }
 
+// Init registers the noop driver as a backend for Chihaya.
 func init() {
 	backend.Register("noop", &driver{})
 }

chihaya.go

@@ -33,6 +33,8 @@ func init() {
 	flag.StringVar(&configPath, "config", "", "path to the configuration file")
 }
 
+// Boot starts Chihaya. By exporting this function, anyone can import their own
+// custom drivers into their own package main and then call chihaya.Boot.
 func Boot() {
 	defer glog.Flush()
 

http/writer.go

@@ -12,10 +12,12 @@ import (
 	"github.com/chihaya/chihaya/tracker/models"
 )
 
+// Writer implements the tracker.Writer interface for the HTTP protocol.
 type Writer struct {
 	http.ResponseWriter
 }
 
+// WriteError writes a bencode dict with a failure reason.
 func (w *Writer) WriteError(err error) error {
 	bencoder := bencode.NewEncoder(w)
 
@@ -24,6 +26,7 @@ func (w *Writer) WriteError(err error) error {
 	})
 }
 
+// WriteAnnounce writes a bencode dict representation of an AnnounceResponse.
 func (w *Writer) WriteAnnounce(res *models.AnnounceResponse) error {
 	dict := bencode.Dict{
 		"complete":     res.Complete,
@@ -45,6 +48,7 @@ func (w *Writer) WriteAnnounce(res *models.AnnounceResponse) error {
 	return bencoder.Encode(dict)
 }
 
+// WriteScrape writes a bencode dict representation of a ScrapeResponse.
 func (w *Writer) WriteScrape(res *models.ScrapeResponse) error {
 	dict := bencode.Dict{
 		"files": filesDict(res.Files),

tracker/announce.go

@@ -10,6 +10,8 @@ import (
 	"github.com/chihaya/chihaya/tracker/models"
 )
 
+// HandleAnnounce encapsulates all of the logic of handling a BitTorrent
+// client's Announce without being coupled to any transport protocol.
 func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error {
 	conn, err := t.Pool.Get()
 	if err != nil {
@@ -62,7 +64,7 @@ func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error {
 
 	peer := models.NewPeer(ann, user, torrent)
 
-	created, err := updateTorrent(conn, ann, peer, torrent)
+	created, err := updateSwarm(conn, ann, peer, torrent)
 	if err != nil {
 		return err
 	}
@@ -87,7 +89,8 @@ func (t *Tracker) HandleAnnounce(ann *models.Announce, w Writer) error {
 	return w.WriteAnnounce(newAnnounceResponse(ann, peer, torrent))
 }
 
-func updateTorrent(c Conn, ann *models.Announce, p *models.Peer, t *models.Torrent) (created bool, err error) {
+// updateSwarm handles the changes to a torrent's swarm given an announce.
+func updateSwarm(c Conn, ann *models.Announce, p *models.Peer, t *models.Torrent) (created bool, err error) {
 	c.TouchTorrent(t.Infohash)
 
 	switch {
@@ -125,6 +128,8 @@ func updateTorrent(c Conn, ann *models.Announce, p *models.Peer, t *models.Torre
 	return
 }
 
+// handleEvent checks to see whether an announce has an event and if it does,
+// properly handles that event.
 func handleEvent(c Conn, ann *models.Announce, p *models.Peer, u *models.User, t *models.Torrent) (snatched bool, err error) {
 	switch {
 	case ann.Event == "stopped" || ann.Event == "paused":
@@ -187,6 +192,8 @@ func newAnnounceResponse(ann *models.Announce, announcer *models.Peer, t *models
 	return res
 }
 
+// getPeers returns lists IPv4 and IPv6 peers on a given torrent sized according
+// to the wanted parameter.
 func getPeers(ann *models.Announce, announcer *models.Peer, t *models.Torrent, wanted int) (ipv4s, ipv6s models.PeerList) {
 	ipv4s, ipv6s = models.PeerList{}, models.PeerList{}
 
@@ -200,6 +207,7 @@ func getPeers(ann *models.Announce, announcer *models.Peer, t *models.Torrent, w
 	return appendPeers(ipv4s, ipv6s, ann, announcer, t.Leechers, wanted-len(ipv4s)-len(ipv6s))
 }
 
+// appendPeers implements the logic of adding peers to the IPv4 or IPv6 lists.
 func appendPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer *models.Peer, peers models.PeerMap, wanted int) (models.PeerList, models.PeerList) {
 	if ann.Config.PreferredSubnet {
 		return appendSubnetPeers(ipv4s, ipv6s, ann, announcer, peers, wanted)
@@ -228,6 +236,8 @@ func appendPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer *
 	return ipv4s, ipv6s
 }
 
+// appendSubnetPeers is an alternative version of appendPeers used when the
+// config variable PreferredSubnet is enabled.
 func appendSubnetPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, announcer *models.Peer, peers models.PeerMap, wanted int) (models.PeerList, models.PeerList) {
 	var subnet net.IPNet
 
@@ -264,6 +274,7 @@ func appendSubnetPeers(ipv4s, ipv6s models.PeerList, ann *models.Announce, annou
 	return ipv4s, ipv6s
 }
 
+// peersEquivalent checks if two peers are one in the same.
 func peersEquivalent(a, b *models.Peer) bool {
 	return a.ID == b.ID || a.UserID != 0 && a.UserID == b.UserID
 }

tracker/models/models.go

@@ -14,7 +14,7 @@ import (
 )
 
 var (
-	// ErrMalformedRequest is returned when an http.Request does not have the
+	// ErrMalformedRequest is returned when a client request does not have the
 	// required parameters to create a model.
 	ErrMalformedRequest = errors.New("malformed request")
 )
@@ -69,8 +69,7 @@ func NewPeer(a *Announce, u *User, t *Torrent) *Peer {
 	}
 }
 
-// Key returns the unique key used to look-up a peer in a swarm (i.e
+// Key returns the unique key used to look-up a peer in a PeerMap.
-// Torrent.Seeders & Torrent.Leechers).
 func (p Peer) Key() string {
 	return p.ID + ":" + strconv.FormatUint(p.UserID, 36)
 }

tracker/scrape.go

@@ -8,6 +8,8 @@ import (
 	"github.com/chihaya/chihaya/tracker/models"
 )
 
+// HandleScrape encapsulates all the logic of handling a BitTorrent client's
+// scrape without being coupled to any transport protocol.
 func (t *Tracker) HandleScrape(scrape *models.Scrape, w Writer) error {
 	conn, err := t.Pool.Get()
 	if err != nil {