a few more comments

blocks/blocks.go

@@ -19,6 +19,9 @@ func NewBlock(data []byte) *Block {
 	return &Block{Data: data, Multihash: u.Hash(data)}
 }
 
+// NewBlockWithHash creates a new block when the hash of the data
+// is already known, this is used to save time in situations where
+// we are able to be confident that the data is correct
 func NewBlockWithHash(data []byte, h mh.Multihash) (*Block, error) {
 	if u.Debug {
 		chk := u.Hash(data)

merkledag/merkledag.go

@@ -48,6 +48,7 @@ type Link struct {
 	Node *Node
 }
 
+// MakeLink creates a link to the given node
 func MakeLink(n *Node) (*Link, error) {
 	s, err := n.Size()
 	if err != nil {
@@ -64,6 +65,7 @@ func MakeLink(n *Node) (*Link, error) {
 	}, nil
 }
 
+// GetNode returns the MDAG Node that this link points to
 func (l *Link) GetNode(serv DAGService) (*Node, error) {
 	if l.Node != nil {
 		return l.Node, nil
@@ -98,6 +100,7 @@ func (n *Node) AddNodeLinkClean(name string, that *Node) error {
 	return nil
 }
 
+// Remove a link on this node by the given name
 func (n *Node) RemoveNodeLink(name string) error {
 	for i, l := range n.Links {
 		if l.Name == name {
@@ -196,6 +199,7 @@ func (n *dagService) Add(nd *Node) (u.Key, error) {
 	return n.Blocks.AddBlock(b)
 }
 
+// AddRecursive adds the given node and all child nodes to the BlockService
 func (n *dagService) AddRecursive(nd *Node) error {
 	_, err := n.Add(nd)
 	if err != nil {
@@ -230,6 +234,7 @@ func (n *dagService) Get(k u.Key) (*Node, error) {
 	return Decoded(b.Data)
 }
 
+// Remove deletes the given node and all of its children from the BlockService
 func (n *dagService) Remove(nd *Node) error {
 	for _, l := range nd.Links {
 		if l.Node != nil {
@@ -243,6 +248,8 @@ func (n *dagService) Remove(nd *Node) error {
 	return n.Blocks.DeleteBlock(k)
 }
 
+// FetchGraph asynchronously fetches all nodes that are children of the given
+// node, and returns a channel that may be waited upon for the fetch to complete
 func FetchGraph(ctx context.Context, root *Node, serv DAGService) chan struct{} {
 	var wg sync.WaitGroup
 	done := make(chan struct{})

namesys/publisher.go

@@ -26,6 +26,7 @@ func NewRoutingPublisher(route routing.IpfsRouting) Publisher {
 }
 
 // Publish implements Publisher. Accepts a keypair and a value,
+// and publishes it out to the routing system
 func (p *ipnsPublisher) Publish(k ci.PrivKey, value string) error {
 	log.Debugf("namesys: Publish %s", value)
 

peer/peer.go

@@ -274,6 +274,7 @@ func (p *peer) VerifyAndSetPubKey(pk ic.PubKey) error {
 	panic("invariant violated: unexpected key mismatch")
 }
 
+// Updates this peer with information from another peer instance
 func (p *peer) Update(other Peer) error {
 	if !p.ID().Equal(other.ID()) {
 		return errors.New("peer ids do not match")

pin/pin.go

 package pin
 
 import (
-
-	//ds "github.com/jbenet/go-ipfs/Godeps/_workspace/src/github.com/jbenet/datastore.go"
-
 	"encoding/json"
 	"errors"
 	"sync"
@@ -36,12 +33,14 @@ type Pinner interface {
 }
 
 // ManualPinner is for manually editing the pin structure
-// Use with care
+// Use with care! If used improperly, garbage collection
+// may not be successful
 type ManualPinner interface {
 	PinWithMode(util.Key, PinMode)
 	Pinner
 }
 
+// pinner implements the Pinner interface
 type pinner struct {
 	lock       sync.RWMutex
 	recursePin set.BlockSet
@@ -51,6 +50,7 @@ type pinner struct {
 	dstore     ds.Datastore
 }
 
+// NewPinner creates a new pinner using the given datastore as a backend
 func NewPinner(dstore ds.Datastore, serv mdag.DAGService) Pinner {
 
 	// Load set from given datastore...
@@ -70,6 +70,7 @@ func NewPinner(dstore ds.Datastore, serv mdag.DAGService) Pinner {
 	}
 }
 
+// Pin the given node, optionally recursive
 func (p *pinner) Pin(node *mdag.Node, recurse bool) error {
 	p.lock.Lock()
 	defer p.lock.Unlock()
@@ -95,6 +96,7 @@ func (p *pinner) Pin(node *mdag.Node, recurse bool) error {
 	return nil
 }
 
+// Unpin a given key with optional recursive unpinning
 func (p *pinner) Unpin(k util.Key, recurse bool) error {
 	p.lock.Lock()
 	defer p.lock.Unlock()
@@ -158,6 +160,7 @@ func (p *pinner) pinLinks(node *mdag.Node) error {
 	return nil
 }
 
+// IsPinned returns whether or not the given key is pinned
 func (p *pinner) IsPinned(key util.Key) bool {
 	p.lock.RLock()
 	defer p.lock.RUnlock()
@@ -166,6 +169,7 @@ func (p *pinner) IsPinned(key util.Key) bool {
 		p.indirPin.HasKey(key)
 }
 
+// LoadPinner loads a pinner and its keysets from the given datastore
 func LoadPinner(d ds.Datastore, dserv mdag.DAGService) (Pinner, error) {
 	p := new(pinner)
 
@@ -200,6 +204,7 @@ func LoadPinner(d ds.Datastore, dserv mdag.DAGService) (Pinner, error) {
 	return p, nil
 }
 
+// Flush encodes and writes pinner keysets to the datastore
 func (p *pinner) Flush() error {
 	p.lock.RLock()
 	defer p.lock.RUnlock()
@@ -244,6 +249,8 @@ func loadSet(d ds.Datastore, k ds.Key, val interface{}) error {
 	return json.Unmarshal(bf, val)
 }
 
+// PinWithMode is a method on ManualPinners, allowing the user to have fine
+// grained control over pin counts
 func (p *pinner) PinWithMode(k util.Key, mode PinMode) {
 	switch mode {
 	case Recursive: