Merge pull request #4665 from ipfs/doc/golint-merkledag

Golint: fix golint warnings in merkledag submodule

merkledag/coding.go

@@ -102,7 +102,7 @@ func (n *ProtoNode) EncodeProtobuf(force bool) ([]byte, error) {
 	return n.encoded, nil
 }
 
-// Decoded decodes raw data and returns a new Node instance.
+// DecodeProtobuf decodes raw data and returns a new Node instance.
 func DecodeProtobuf(encoded []byte) (*ProtoNode, error) {
 	n := new(ProtoNode)
 	err := n.unmarshal(encoded)

merkledag/errservice.go

@@ -14,28 +14,34 @@ type ErrorService struct {
 
 var _ ipld.DAGService = (*ErrorService)(nil)
 
+// Add returns the cs.Err.
 func (cs *ErrorService) Add(ctx context.Context, nd ipld.Node) error {
 	return cs.Err
 }
 
+// AddMany returns the cs.Err.
 func (cs *ErrorService) AddMany(ctx context.Context, nds []ipld.Node) error {
 	return cs.Err
 }
 
+// Get returns the cs.Err.
 func (cs *ErrorService) Get(ctx context.Context, c *cid.Cid) (ipld.Node, error) {
 	return nil, cs.Err
 }
 
+// GetMany many returns the cs.Err.
 func (cs *ErrorService) GetMany(ctx context.Context, cids []*cid.Cid) <-chan *ipld.NodeOption {
 	ch := make(chan *ipld.NodeOption)
 	close(ch)
 	return ch
 }
 
+// Remove returns the cs.Err.
 func (cs *ErrorService) Remove(ctx context.Context, c *cid.Cid) error {
 	return cs.Err
 }
 
+// RemoveMany returns the cs.Err.
 func (cs *ErrorService) RemoveMany(ctx context.Context, cids []*cid.Cid) error {
 	return cs.Err
 }

merkledag/merkledag.go

@@ -1,4 +1,4 @@
-// package merkledag implements the IPFS Merkle DAG datastructures.
+// Package merkledag implements the IPFS Merkle DAG data structures.
 package merkledag
 
 import (
@@ -23,7 +23,13 @@ func init() {
 	ipld.Register(cid.DagCBOR, ipldcbor.DecodeBlock)
 }
 
+// contextKey is a type to use as value for the ProgressTracker contexts.
+type contextKey string
+
+const progressContextKey contextKey = "progress"
+
 // NewDAGService constructs a new DAGService (using the default implementation).
+// Note that the default implementation is also an ipld.LinkGetter.
 func NewDAGService(bs bserv.BlockService) *dagService {
 	return &dagService{Blocks: bs}
 }
@@ -147,8 +153,8 @@ func (sg *sesGetter) GetMany(ctx context.Context, keys []*cid.Cid) <-chan *ipld.
 }
 
 // Session returns a NodeGetter using a new session for block fetches.
-func (ds *dagService) Session(ctx context.Context) ipld.NodeGetter {
-	return &sesGetter{bserv.NewSession(ctx, ds.Blocks)}
+func (n *dagService) Session(ctx context.Context) ipld.NodeGetter {
+	return &sesGetter{bserv.NewSession(ctx, n.Blocks)}
 }
 
 // FetchGraph fetches all nodes that are children of the given node
@@ -159,7 +165,7 @@ func FetchGraph(ctx context.Context, root *cid.Cid, serv ipld.DAGService) error
 		ng = &sesGetter{bserv.NewSession(ctx, ds.Blocks)}
 	}
 
-	v, _ := ctx.Value("progress").(*ProgressTracker)
+	v, _ := ctx.Value(progressContextKey).(*ProgressTracker)
 	if v == nil {
 		return EnumerateChildrenAsync(ctx, GetLinksDirect(ng), root, cid.NewSet().Visit)
 	}
@@ -168,9 +174,8 @@ func FetchGraph(ctx context.Context, root *cid.Cid, serv ipld.DAGService) error
 		if set.Visit(c) {
 			v.Increment()
 			return true
-		} else {
-			return false
 		}
+		return false
 	}
 	return EnumerateChildrenAsync(ctx, GetLinksDirect(ng), root, visit)
 }
@@ -179,8 +184,8 @@ func FetchGraph(ctx context.Context, root *cid.Cid, serv ipld.DAGService) error
 // returns the indexes of any links pointing to it
 func FindLinks(links []*cid.Cid, c *cid.Cid, start int) []int {
 	var out []int
-	for i, lnk_c := range links[start:] {
-		if c.Equals(lnk_c) {
+	for i, lnkC := range links[start:] {
+		if c.Equals(lnkC) {
 			out = append(out, i+start)
 		}
 	}
@@ -265,21 +270,26 @@ func EnumerateChildren(ctx context.Context, getLinks GetLinks, root *cid.Cid, vi
 	return nil
 }
 
+// ProgressTracker is used to show progress when fetching nodes.
 type ProgressTracker struct {
 	Total int
 	lk    sync.Mutex
 }
 
+// DeriveContext returns a new context with value "progress" derived from
+// the given one.
 func (p *ProgressTracker) DeriveContext(ctx context.Context) context.Context {
-	return context.WithValue(ctx, "progress", p)
+	return context.WithValue(ctx, progressContextKey, p)
 }
 
+// Increment adds one to the total progress.
 func (p *ProgressTracker) Increment() {
 	p.lk.Lock()
 	defer p.lk.Unlock()
 	p.Total++
 }
 
+// Value returns the current progress.
 func (p *ProgressTracker) Value() int {
 	p.lk.Lock()
 	defer p.lk.Unlock()

merkledag/merkledag_test.go

@@ -22,11 +22,11 @@ import (
 	mdpb "github.com/ipfs/go-ipfs/merkledag/pb"
 	dstest "github.com/ipfs/go-ipfs/merkledag/test"
 	uio "github.com/ipfs/go-ipfs/unixfs/io"
-	blocks "gx/ipfs/Qmej7nf81hi2x2tvjRBF3mcp74sQyuDH4VMYDGd1YtXjb2/go-block-format"
 
 	u "gx/ipfs/QmNiJuT8Ja3hMVpBHXv3Q6dwmperaQ6JjLtpMQgMCD7xvx/go-ipfs-util"
 	cid "gx/ipfs/QmcZfnkapfECQGcLZaf9B79NRg7cRa9EnZh4LSbkCzwNvY/go-cid"
 	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
+	blocks "gx/ipfs/Qmej7nf81hi2x2tvjRBF3mcp74sQyuDH4VMYDGd1YtXjb2/go-block-format"
 )
 
 func TestNode(t *testing.T) {
@@ -241,9 +241,9 @@ func TestFetchGraph(t *testing.T) {
 	// create an offline dagstore and ensure all blocks were fetched
 	bs := bserv.New(bsis[1].Blockstore(), offline.Exchange(bsis[1].Blockstore()))
 
-	offline_ds := NewDAGService(bs)
+	offlineDS := NewDAGService(bs)
 
-	err = EnumerateChildren(context.Background(), offline_ds.GetLinks, root.Cid(), func(_ *cid.Cid) bool { return true })
+	err = EnumerateChildren(context.Background(), offlineDS.GetLinks, root.Cid(), func(_ *cid.Cid) bool { return true })
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -260,6 +260,7 @@ func TestEnumerateChildren(t *testing.T) {
 	}
 
 	set := cid.NewSet()
+
 	err = EnumerateChildren(context.Background(), ds.GetLinks, root.Cid(), set.Visit)
 	if err != nil {
 		t.Fatal(err)

merkledag/node.go

@@ -10,10 +10,13 @@ import (
 	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
 )
 
-var ErrNotProtobuf = fmt.Errorf("expected protobuf dag node")
-var ErrLinkNotFound = fmt.Errorf("no link by that name")
+// Common errors
+var (
+	ErrNotProtobuf  = fmt.Errorf("expected protobuf dag node")
+	ErrLinkNotFound = fmt.Errorf("no link by that name")
+)
 
-// Node represents a node in the IPFS Merkle DAG.
+// ProtoNode represents a node in the IPFS Merkle DAG.
 // nodes have opaque data and a set of navigable links.
 type ProtoNode struct {
 	links []*ipld.Link
@@ -73,12 +76,14 @@ func (n *ProtoNode) SetPrefix(prefix *cid.Prefix) {
 	}
 }
 
+// LinkSlice is a slice of ipld.Links
 type LinkSlice []*ipld.Link
 
 func (ls LinkSlice) Len() int           { return len(ls) }
 func (ls LinkSlice) Swap(a, b int)      { ls[a], ls[b] = ls[b], ls[a] }
 func (ls LinkSlice) Less(a, b int) bool { return ls[a].Name < ls[b].Name }
 
+// NodeWithData builds a new Protonode with the given data.
 func NodeWithData(d []byte) *ProtoNode {
 	return &ProtoNode{data: d}
 }
@@ -204,15 +209,18 @@ func (n *ProtoNode) Copy() ipld.Node {
 	return nnode
 }
 
+// RawData returns the protobuf-encoded version of the node.
 func (n *ProtoNode) RawData() []byte {
 	out, _ := n.EncodeProtobuf(false)
 	return out
 }
 
+// Data returns the data stored by this node.
 func (n *ProtoNode) Data() []byte {
 	return n.data
 }
 
+// SetData stores data in this nodes.
 func (n *ProtoNode) SetData(d []byte) {
 	n.encoded = nil
 	n.cached = nil
@@ -265,12 +273,14 @@ func (n *ProtoNode) Stat() (*ipld.NodeStat, error) {
 	}, nil
 }
 
+// Loggable implements the ipfs/go-log.Loggable interface.
 func (n *ProtoNode) Loggable() map[string]interface{} {
 	return map[string]interface{}{
 		"node": n.String(),
 	}
 }
 
+// UnmarshalJSON reads the node fields from a JSON-encoded byte slice.
 func (n *ProtoNode) UnmarshalJSON(b []byte) error {
 	s := struct {
 		Data  []byte       `json:"data"`
@@ -287,6 +297,7 @@ func (n *ProtoNode) UnmarshalJSON(b []byte) error {
 	return nil
 }
 
+// MarshalJSON returns a JSON representation of the node.
 func (n *ProtoNode) MarshalJSON() ([]byte, error) {
 	out := map[string]interface{}{
 		"data":  n.data,
@@ -296,6 +307,8 @@ func (n *ProtoNode) MarshalJSON() ([]byte, error) {
 	return json.Marshal(out)
 }
 
+// Cid returns the node's Cid, calculated according to its prefix
+// and raw data contents.
 func (n *ProtoNode) Cid() *cid.Cid {
 	if n.encoded != nil && n.cached != nil {
 		return n.cached
@@ -316,6 +329,7 @@ func (n *ProtoNode) Cid() *cid.Cid {
 	return c
 }
 
+// String prints the node's Cid.
 func (n *ProtoNode) String() string {
 	return n.Cid().String()
 }
@@ -332,18 +346,24 @@ func (n *ProtoNode) Multihash() mh.Multihash {
 	return n.cached.Hash()
 }
 
+// Links returns the node links.
 func (n *ProtoNode) Links() []*ipld.Link {
 	return n.links
 }
 
+// SetLinks replaces the node links with the given ones.
 func (n *ProtoNode) SetLinks(links []*ipld.Link) {
 	n.links = links
 }
 
+// Resolve is an alias for ResolveLink.
 func (n *ProtoNode) Resolve(path []string) (interface{}, []string, error) {
 	return n.ResolveLink(path)
 }
 
+// ResolveLink consumes the first element of the path and obtains the link
+// corresponding to it from the node. It returns the link
+// and the path without the consumed element.
 func (n *ProtoNode) ResolveLink(path []string) (*ipld.Link, []string, error) {
 	if len(path) == 0 {
 		return nil, nil, fmt.Errorf("end of path, no more links to resolve")
@@ -357,9 +377,10 @@ func (n *ProtoNode) ResolveLink(path []string) (*ipld.Link, []string, error) {
 	return lnk, path[1:], nil
 }
 
+// Tree returns the link names of the ProtoNode.
+// ProtoNodes are only ever one path deep, so anything different than an empty
+// string for p results in nothing. The depth parameter is ignored.
 func (n *ProtoNode) Tree(p string, depth int) []string {
-	// ProtoNodes are only ever one path deep, anything below that results in
-	// nothing
 	if p != "" {
 		return nil
 	}

merkledag/raw.go

@@ -9,6 +9,7 @@ import (
 	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
 )
 
+// RawNode represents a node which only contains data.
 type RawNode struct {
 	blocks.Block
 }
@@ -52,22 +53,27 @@ func NewRawNodeWPrefix(data []byte, prefix cid.Prefix) (*RawNode, error) {
 	return &RawNode{blk}, nil
 }
 
+// Links returns nil.
 func (rn *RawNode) Links() []*ipld.Link {
 	return nil
 }
 
+// ResolveLink returns an error.
 func (rn *RawNode) ResolveLink(path []string) (*ipld.Link, []string, error) {
 	return nil, nil, ErrLinkNotFound
 }
 
+// Resolve returns an error.
 func (rn *RawNode) Resolve(path []string) (interface{}, []string, error) {
 	return nil, nil, ErrLinkNotFound
 }
 
+// Tree returns nil.
 func (rn *RawNode) Tree(p string, depth int) []string {
 	return nil
 }
 
+// Copy performs a deep copy of this node and returns it as an ipld.Node
 func (rn *RawNode) Copy() ipld.Node {
 	copybuf := make([]byte, len(rn.RawData()))
 	copy(copybuf, rn.RawData())
@@ -80,10 +86,12 @@ func (rn *RawNode) Copy() ipld.Node {
 	return &RawNode{nblk}
 }
 
+// Size returns the size of this node
 func (rn *RawNode) Size() (uint64, error) {
 	return uint64(len(rn.RawData())), nil
 }
 
+// Stat returns some Stats about this node.
 func (rn *RawNode) Stat() (*ipld.NodeStat, error) {
 	return &ipld.NodeStat{
 		CumulativeSize: len(rn.RawData()),

merkledag/rwservice.go

@@ -16,26 +16,32 @@ type ComboService struct {
 
 var _ ipld.DAGService = (*ComboService)(nil)
 
+// Add writes a new node using the Write DAGService.
 func (cs *ComboService) Add(ctx context.Context, nd ipld.Node) error {
 	return cs.Write.Add(ctx, nd)
 }
 
+// AddMany adds nodes using the Write DAGService.
 func (cs *ComboService) AddMany(ctx context.Context, nds []ipld.Node) error {
 	return cs.Write.AddMany(ctx, nds)
 }
 
+// Get fetches a node using the Read DAGService.
 func (cs *ComboService) Get(ctx context.Context, c *cid.Cid) (ipld.Node, error) {
 	return cs.Read.Get(ctx, c)
 }
 
+// GetMany fetches nodes using the Read DAGService.
 func (cs *ComboService) GetMany(ctx context.Context, cids []*cid.Cid) <-chan *ipld.NodeOption {
 	return cs.Read.GetMany(ctx, cids)
 }
 
+// Remove deletes a node using the Write DAGService.
 func (cs *ComboService) Remove(ctx context.Context, c *cid.Cid) error {
 	return cs.Write.Remove(ctx, c)
 }
 
+// RemoveMany deletes nodes using the Write DAGService.
 func (cs *ComboService) RemoveMany(ctx context.Context, cids []*cid.Cid) error {
 	return cs.Write.RemoveMany(ctx, cids)
 }