Merge pull request #4696 from ipfs/doc/golint-pin

Doc: golint-ify pin package

core/commands/pin.go

@@ -494,7 +494,7 @@ type RefKeyList struct {
 
 func pinLsKeys(args []string, typeStr string, ctx context.Context, n *core.IpfsNode) (map[string]RefKeyObject, error) {
 
-	mode, ok := pin.StringToPinMode(typeStr)
+	mode, ok := pin.StringToMode(typeStr)
 	if !ok {
 		return nil, fmt.Errorf("invalid pin mode '%s'", typeStr)
 	}

pin/gc/gc.go

@@ -1,3 +1,4 @@
+// Package gc provides garbage collection for go-ipfs.
 package gc
 
 import (
@@ -35,7 +36,6 @@ type Result struct {
 //
 // The routine then iterates over every block in the blockstore and
 // deletes any block that is not found in the marked set.
-//
 func GC(ctx context.Context, bs bstore.GCBlockstore, dstor dstore.Datastore, pn pin.Pinner, bestEffortRoots []*cid.Cid) <-chan Result {
 
 	elock := log.EventBegin(ctx, "GC.lockWait")
@@ -125,6 +125,9 @@ func GC(ctx context.Context, bs bstore.GCBlockstore, dstor dstore.Datastore, pn
 	return output
 }
 
+// Descendants recursively finds all the descendants of the given roots and
+// adds them to the given cid.Set, using the provided dag.GetLinks function
+// to walk the tree.
 func Descendants(ctx context.Context, getLinks dag.GetLinks, set *cid.Set, roots []*cid.Cid) error {
 	for _, c := range roots {
 		set.Add(c)
@@ -191,24 +194,38 @@ func ColoredSet(ctx context.Context, pn pin.Pinner, ng ipld.NodeGetter, bestEffo
 	return gcs, nil
 }
 
+// ErrCannotFetchAllLinks is returned as the last Result in the GC output
+// channel when there was a error creating the marked set because of a
+// problem when finding descendants.
 var ErrCannotFetchAllLinks = errors.New("garbage collection aborted: could not retrieve some links")
 
+// ErrCannotDeleteSomeBlocks is returned when removing blocks marked for
+// deletion fails as the last Result in GC output channel.
 var ErrCannotDeleteSomeBlocks = errors.New("garbage collection incomplete: could not delete some blocks")
 
+// CannotFetchLinksError provides detailed information about which links
+// could not be fetched and can appear as a Result in the GC output channel.
 type CannotFetchLinksError struct {
 	Key *cid.Cid
 	Err error
 }
 
+// Error implements the error interface for this type with a useful
+// message.
 func (e *CannotFetchLinksError) Error() string {
 	return fmt.Sprintf("could not retrieve links for %s: %s", e.Key, e.Err)
 }
 
+// CannotDeleteBlockError provides detailed information about which
+// blocks could not be deleted and can appear as a Result in the GC output
+// channel.
 type CannotDeleteBlockError struct {
 	Key *cid.Cid
 	Err error
 }
 
+// Error implements the error interface for this type with a
+// useful message.
 func (e *CannotDeleteBlockError) Error() string {
 	return fmt.Sprintf("could not remove %s: %s", e.Key, e.Err)
 }

pin/pin.go

@@ -1,4 +1,4 @@
-// package pin implements structures and methods to keep track of
+// Package pin implements structures and methods to keep track of
 // which objects a user wants to keep stored locally.
 package pin
 
@@ -43,11 +43,14 @@ const (
 	linkAll       = "all"
 )
 
-type PinMode int
+// Mode allows to specify different types of pin (recursive, direct etc.).
+// See the Pin Modes constants for a full list.
+type Mode int
 
+// Pin Modes
 const (
 	// Recursive pins pin the target cids along with any reachable children.
-	Recursive PinMode = iota
+	Recursive Mode = iota
 
 	// Direct pins pin just the target cid.
 	Direct
@@ -65,8 +68,9 @@ const (
 	Any
 )
 
-func PinModeToString(mode PinMode) (string, bool) {
+// ModeToString returns a human-readable name for the Mode.
-	m := map[PinMode]string{
+func ModeToString(mode Mode) (string, bool) {
+	m := map[Mode]string{
 		Recursive: linkRecursive,
 		Direct:    linkDirect,
 		Indirect:  linkIndirect,
@@ -78,8 +82,10 @@ func PinModeToString(mode PinMode) (string, bool) {
 	return s, ok
 }
 
-func StringToPinMode(s string) (PinMode, bool) {
+// StringToMode parses the result of ModeToString() back to a Mode.
-	m := map[string]PinMode{
+// It returns a boolean which is set to false if the mode is unknown.
+func StringToMode(s string) (Mode, bool) {
+	m := map[string]Mode{
 		linkRecursive: Recursive,
 		linkDirect:    Direct,
 		linkIndirect:  Indirect,
@@ -92,6 +98,10 @@ func StringToPinMode(s string) (PinMode, bool) {
 	return mode, ok
 }
 
+// A Pinner provides the necessary methods to keep track of Nodes which are
+// to be kept locally, according to a pin mode. In practice, a Pinner is in
+// in charge of keeping the list of items from the local storage that should
+// not be garbaged-collected.
 type Pinner interface {
 	// IsPinned returns whether or not the given cid is pinned
 	// and an explanation of why its pinned
@@ -99,7 +109,7 @@ type Pinner interface {
 
 	// IsPinnedWithType returns whether or not the given cid is pinned with the
 	// given pin type, as well as returning the type of pin its pinned with.
-	IsPinnedWithType(*cid.Cid, PinMode) (string, bool, error)
+	IsPinnedWithType(*cid.Cid, Mode) (string, bool, error)
 
 	// Pin the given node, optionally recursively.
 	Pin(ctx context.Context, node ipld.Node, recursive bool) error
@@ -120,12 +130,12 @@ type Pinner interface {
 	// PinWithMode is for manually editing the pin structure. Use with
 	// care! If used improperly, garbage collection may not be
 	// successful.
-	PinWithMode(*cid.Cid, PinMode)
+	PinWithMode(*cid.Cid, Mode)
 
 	// RemovePinWithMode is for manually editing the pin structure.
 	// Use with care! If used improperly, garbage collection may not
 	// be successful.
-	RemovePinWithMode(*cid.Cid, PinMode)
+	RemovePinWithMode(*cid.Cid, Mode)
 
 	// Flush writes the pin state to the backing datastore
 	Flush() error
@@ -141,19 +151,19 @@ type Pinner interface {
 	InternalPins() []*cid.Cid
 }
 
+// Pinned represents CID which has been pinned with a pinning strategy.
+// The Via field allows to identify the pinning parent of this CID, in the
+// case that the item is not pinned directly (but rather pinned recursively
+// by some ascendant).
 type Pinned struct {
 	Key  *cid.Cid
-	Mode PinMode
+	Mode Mode
 	Via  *cid.Cid
 }
 
 // Pinned returns whether or not the given cid is pinned
 func (p Pinned) Pinned() bool {
-	if p.Mode == NotPinned {
+	return p.Mode != NotPinned
-		return false
-	} else {
-		return true
-	}
 }
 
 // String Returns pin status as string
@@ -164,7 +174,7 @@ func (p Pinned) String() string {
 	case Indirect:
 		return fmt.Sprintf("pinned via %s", p.Via)
 	default:
-		modeStr, _ := PinModeToString(p.Mode)
+		modeStr, _ := ModeToString(p.Mode)
 		return fmt.Sprintf("pinned: %s", modeStr)
 	}
 }
@@ -240,6 +250,7 @@ func (p *pinner) Pin(ctx context.Context, node ipld.Node, recurse bool) error {
 	return nil
 }
 
+// ErrNotPinned is returned when trying to unpin items which are not pinned.
 var ErrNotPinned = fmt.Errorf("not pinned")
 
 // Unpin a given key
@@ -258,9 +269,8 @@ func (p *pinner) Unpin(ctx context.Context, c *cid.Cid, recursive bool) error {
 		if recursive {
 			p.recursePin.Remove(c)
 			return nil
-		} else {
-			return fmt.Errorf("%s is pinned recursively", c)
 		}
+		return fmt.Errorf("%s is pinned recursively", c)
 	case "direct":
 		p.directPin.Remove(c)
 		return nil
@@ -283,7 +293,7 @@ func (p *pinner) IsPinned(c *cid.Cid) (string, bool, error) {
 
 // IsPinnedWithType returns whether or not the given cid is pinned with the
 // given pin type, as well as returning the type of pin its pinned with.
-func (p *pinner) IsPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error) {
+func (p *pinner) IsPinnedWithType(c *cid.Cid, mode Mode) (string, bool, error) {
 	p.lock.RLock()
 	defer p.lock.RUnlock()
 	return p.isPinnedWithType(c, mode)
@@ -291,7 +301,7 @@ func (p *pinner) IsPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error
 
 // isPinnedWithType is the implementation of IsPinnedWithType that does not lock.
 // intended for use by other pinned methods that already take locks
-func (p *pinner) isPinnedWithType(c *cid.Cid, mode PinMode) (string, bool, error) {
+func (p *pinner) isPinnedWithType(c *cid.Cid, mode Mode) (string, bool, error) {
 	switch mode {
 	case Any, Direct, Indirect, Recursive, Internal:
 	default:
@@ -404,7 +414,7 @@ func (p *pinner) CheckIfPinned(cids ...*cid.Cid) ([]Pinned, error) {
 // RemovePinWithMode is for manually editing the pin structure.
 // Use with care! If used improperly, garbage collection may not
 // be successful.
-func (p *pinner) RemovePinWithMode(c *cid.Cid, mode PinMode) {
+func (p *pinner) RemovePinWithMode(c *cid.Cid, mode Mode) {
 	p.lock.Lock()
 	defer p.lock.Unlock()
 	switch mode {
@@ -584,7 +594,7 @@ func (p *pinner) InternalPins() []*cid.Cid {
 
 // PinWithMode allows the user to have fine grained control over pin
 // counts
-func (p *pinner) PinWithMode(c *cid.Cid, mode PinMode) {
+func (p *pinner) PinWithMode(c *cid.Cid, mode Mode) {
 	p.lock.Lock()
 	defer p.lock.Unlock()
 	switch mode {