interface docs for pinner

License: MIT
Signed-off-by: Jeromy <jeromyj@gmail.com>

pin/pin.go

@@ -46,11 +46,22 @@ const (
 type PinMode int
 
 const (
+	// Recursive pins pin the target cids along with any reachable children.
 	Recursive PinMode = iota
+
+	// Direct pins pin just the target cid.
 	Direct
+
+	// Indirect pins are cids who have some ancestor pinned recursively.
 	Indirect
+
+	// Internal pins are cids used to keep the internal state of the pinner.
 	Internal
+
+	// NotPinned
 	NotPinned
+
+	// Any refers to any pinned cid
 	Any
 )
 
@@ -82,10 +93,20 @@ func StringToPinMode(s string) (PinMode, bool) {
 }
 
 type Pinner interface {
+	// IsPinned returns whether or not the given cid is pinned
+	// and an explanation of why its pinned
 	IsPinned(*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.
 	IsPinnedWithType(*cid.Cid, PinMode) (string, bool, error)
-	Pin(context.Context, node.Node, bool) error
-	Unpin(context.Context, *cid.Cid, bool) error
+
+	// Pin the given node, optionally recursively.
+	Pin(ctx context.Context, node node.Node, recursive bool) error
+
+	// Unpin the given cid. If recursive is true, removes either a recursive or
+	// a direct pin. If recursive is false, only removes a direct pin.
+	Unpin(ctx context.Context, cid *cid.Cid, recursive bool) error
 
 	// Update updates a recursive pin from one cid to another
 	// this is more efficient than simply pinning the new one and unpinning the
@@ -106,9 +127,17 @@ type Pinner interface {
 	// be successful.
 	RemovePinWithMode(*cid.Cid, PinMode)
 
+	// Flush writes the pin state to the backing datastore
 	Flush() error
+
+	// DirectKeys returns all directly pinned cids
 	DirectKeys() []*cid.Cid
+
+	// DirectKeys returns all recursively pinned cids
 	RecursiveKeys() []*cid.Cid
+
+	// InternalPins returns all cids kept pinned for the internal state of the
+	// pinner
 	InternalPins() []*cid.Cid
 }