Merge pull request #4599 from ipfs/feat/doc-interfaces

Feat/doc interfaces

Author: whyrusleeping

blocks/blockstore/blockstore.go

@@ -40,12 +40,19 @@ type Blockstore interface {
 	DeleteBlock(*cid.Cid) error
 	Has(*cid.Cid) (bool, error)
 	Get(*cid.Cid) (blocks.Block, error)
+
+	// Put puts a given block to the underlying datastore
 	Put(blocks.Block) error
+
+	// PutMany puts a slice of blocks at the same time using batching
+	// capabilities of the underlying datastore whenever possible.
 	PutMany([]blocks.Block) error
+
 	// AllKeysChan returns a channel from which
 	// the CIDs in the Blockstore can be read. It should respect
 	// the given context, closing the channel if it becomes Done.
 	AllKeysChan(ctx context.Context) (<-chan *cid.Cid, error)
+
 	// HashOnRead specifies if every read block should be
 	// rehashed to make sure it matches its CID.
 	HashOnRead(enabled bool)

blockservice/blockservice.go

@@ -25,13 +25,26 @@ var ErrNotFound = errors.New("blockservice: key not found")
 // datastore and may retrieve data from a remote Exchange.
 // It uses an internal `datastore.Datastore` instance to store values.
 type BlockService interface {
+	// Blockstore returns a reference to the underlying blockstore
 	Blockstore() blockstore.Blockstore
+
+	// Exchange returns a reference to the underlying exchange (usually bitswap)
 	Exchange() exchange.Interface
+
+	// AddBlock puts a given block to the underlying datastore
 	AddBlock(o blocks.Block) (*cid.Cid, error)
+
+	// AddBlocks adds a slice of blocks at the same time using batching
+	// capabilities of the underlying datastore whenever possible.
 	AddBlocks(bs []blocks.Block) ([]*cid.Cid, error)
+
 	GetBlock(ctx context.Context, c *cid.Cid) (blocks.Block, error)
-	GetBlocks(ctx context.Context, ks []*cid.Cid) <-chan blocks.Block
 	DeleteBlock(o blocks.Block) error
+
+	// GetBlocks does a batch request for the given cids, returning blocks as
+	// they are found, in no particular order.
+	GetBlocks(ctx context.Context, ks []*cid.Cid) <-chan blocks.Block
+
 	Close() error
 }
 

core/builder.go

@@ -115,6 +115,7 @@ func defaultRepo(dstore repo.Datastore) (repo.Repo, error) {
 	}, nil
 }
 
+// NewNode constructs and returns an IpfsNode using the given cfg.
 func NewNode(ctx context.Context, cfg *BuildCfg) (*IpfsNode, error) {
 	if cfg == nil {
 		cfg = new(BuildCfg)

core/core.go

@@ -420,6 +420,8 @@ func setupDiscoveryOption(d config.Discovery) DiscoveryOption {
 	return nil
 }
 
+// HandlePeerFound attempts to connect to peer from `PeerInfo`, if it fails
+// logs a warning log.
 func (n *IpfsNode) HandlePeerFound(p pstore.PeerInfo) {
 	log.Warning("trying peer info: ", p)
 	ctx, cancel := context.WithTimeout(n.Context(), discoveryConnTimeout)
@@ -590,6 +592,7 @@ func (n *IpfsNode) teardown() error {
 	return nil
 }
 
+// OnlineMode returns whether or not the IpfsNode is in OnlineMode.
 func (n *IpfsNode) OnlineMode() bool {
 	switch n.mode {
 	case onlineMode:
@@ -599,13 +602,15 @@ func (n *IpfsNode) OnlineMode() bool {
 	}
 }
 
+// SetLocal will set the IpfsNode to local mode
 func (n *IpfsNode) SetLocal(isLocal bool) {
 	if isLocal {
 		n.mode = localMode
 	}
 	n.localModeSet = true
 }
 
+// LocalMode returns whether or not the IpfsNode is in LocalMode
 func (n *IpfsNode) LocalMode() bool {
 	if !n.localModeSet {
 		// programmer error should not happen
@@ -619,6 +624,7 @@ func (n *IpfsNode) LocalMode() bool {
 	}
 }
 
+// Bootstrap will set and call the IpfsNodes bootstrap function.
 func (n *IpfsNode) Bootstrap(cfg BootstrapConfig) error {
 
 	// TODO what should return value be when in offlineMode?
@@ -670,6 +676,7 @@ func (n *IpfsNode) loadID() error {
 	return nil
 }
 
+// GetKey will return a key from the Keystore with name `name`.
 func (n *IpfsNode) GetKey(name string) (ic.PrivKey, error) {
 	if name == "self" {
 		return n.PrivateKey, nil

core/coreapi/coreapi.go

@@ -15,28 +15,34 @@ type CoreAPI struct {
 	node *core.IpfsNode
 }
 
-// NewCoreAPI creates new instance of IPFS CoreAPI backed by go-ipfs Node
+// NewCoreAPI creates new instance of IPFS CoreAPI backed by go-ipfs Node.
 func NewCoreAPI(n *core.IpfsNode) coreiface.CoreAPI {
 	api := &CoreAPI{n}
 	return api
 }
 
+// Unixfs returns the UnixfsAPI interface backed by the go-ipfs node
 func (api *CoreAPI) Unixfs() coreiface.UnixfsAPI {
 	return (*UnixfsAPI)(api)
 }
 
+// Dag returns the DagAPI interface backed by the go-ipfs node
 func (api *CoreAPI) Dag() coreiface.DagAPI {
 	return &DagAPI{api, nil}
 }
 
+// Name returns the NameAPI interface backed by the go-ipfs node
 func (api *CoreAPI) Name() coreiface.NameAPI {
 	return &NameAPI{api, nil}
 }
 
+// Key returns the KeyAPI interface backed by the go-ipfs node
 func (api *CoreAPI) Key() coreiface.KeyAPI {
 	return &KeyAPI{api, nil}
 }
 
+// ResolveNode resolves the path `p` using Unixfx resolver, gets and returns the
+// resolved Node.
 func (api *CoreAPI) ResolveNode(ctx context.Context, p coreiface.Path) (coreiface.Node, error) {
 	p, err := api.ResolvePath(ctx, p)
 	if err != nil {
@@ -50,6 +56,8 @@ func (api *CoreAPI) ResolveNode(ctx context.Context, p coreiface.Path) (coreifac
 	return node, nil
 }
 
+// ResolvePath resolves the path `p` using Unixfs resolver, returns the
+// resolved path.
 // TODO: store all of ipfspath.Resolver.ResolvePathComponents() in Path
 func (api *CoreAPI) ResolvePath(ctx context.Context, p coreiface.Path) (coreiface.Path, error) {
 	if p.Resolved() {
@@ -84,6 +92,7 @@ type path struct {
 	root *cid.Cid
 }
 
+// ParsePath parses path `p` using ipfspath parser, returns the parsed path.
 func ParsePath(p string) (coreiface.Path, error) {
 	pp, err := ipfspath.ParsePath(p)
 	if err != nil {
@@ -92,10 +101,12 @@ func ParsePath(p string) (coreiface.Path, error) {
 	return &path{path: pp}, nil
 }
 
+// ParseCid parses the path from `c`, retruns the parsed path.
 func ParseCid(c *cid.Cid) coreiface.Path {
 	return &path{path: ipfspath.FromCid(c), cid: c, root: c}
 }
 
+// ResolvePath parses path from string `p`, returns parsed path.
 func ResolvedPath(p string, c *cid.Cid, r *cid.Cid) coreiface.Path {
 	return &path{path: ipfspath.FromString(p), cid: c, root: r}
 }

core/coreapi/dag.go

@@ -19,6 +19,9 @@ type DagAPI struct {
 	*caopts.DagOptions
 }
 
+// Put inserts data using specified format and input encoding. Unless used with
+// `WithCodes` or `WithHash`, the defaults "dag-cbor" and "sha256" are used.
+// Returns the path of the inserted data.
 func (api *DagAPI) Put(ctx context.Context, src io.Reader, opts ...caopts.DagPutOption) (coreiface.Path, error) {
 	settings, err := caopts.DagPutOptions(opts...)
 	if err != nil {
@@ -46,10 +49,12 @@ func (api *DagAPI) Put(ctx context.Context, src io.Reader, opts ...caopts.DagPut
 	return ParseCid(nds[0].Cid()), nil
 }
 
+// Get resolves `path` using Unixfs resolver, returns the resolved Node.
 func (api *DagAPI) Get(ctx context.Context, path coreiface.Path) (coreiface.Node, error) {
 	return api.core().ResolveNode(ctx, path)
 }
 
+// Tree returns list of paths within a node specified by the path `p`.
 func (api *DagAPI) Tree(ctx context.Context, p coreiface.Path, opts ...caopts.DagTreeOption) ([]coreiface.Path, error) {
 	settings, err := caopts.DagTreeOptions(opts...)
 	if err != nil {

core/coreapi/interface/interface.go

@@ -17,9 +17,13 @@ import (
 // Path is a generic wrapper for paths used in the API. A path can be resolved
 // to a CID using one of Resolve functions in the API.
 type Path interface {
+	// String returns the path as a string.
 	String() string
+	// Cid returns cid referred to by path
 	Cid() *cid.Cid
+	// Root returns cid of root path
 	Root() *cid.Cid
+	// Resolved returns whether path has been fully resolved
 	Resolved() bool
 }
 
@@ -33,22 +37,31 @@ type Reader interface {
 	io.Closer
 }
 
+// IpnsEntry specifies the interface to IpnsEntries
 type IpnsEntry interface {
+	// Name returns IpnsEntry name
 	Name() string
+	// Value returns IpnsEntry value
 	Value() Path
 }
 
+// Key specifies the interface to Keys in KeyAPI Keystore
 type Key interface {
+	// Key returns key name
 	Name() string
+	// Path returns key path
 	Path() Path
 }
 
 // CoreAPI defines an unified interface to IPFS for Go programs.
 type CoreAPI interface {
-	// Unixfs returns an implementation of Unixfs API
+	// Unixfs returns an implementation of Unixfs API.
 	Unixfs() UnixfsAPI
+	// Dag returns an implementation of Dag API.
 	Dag() DagAPI
+	// Name returns an implementation of Name API.
 	Name() NameAPI
+	// Key returns an implementation of Key API.
 	Key() KeyAPI
 
 	// ResolvePath resolves the path using Unixfs resolver

core/coreapi/key.go

@@ -24,14 +24,18 @@ type key struct {
 	peerId string
 }
 
+// Name returns the key name
 func (k *key) Name() string {
 	return k.name
 }
 
+// Path returns the path of the key.
 func (k *key) Path() coreiface.Path {
 	return &path{path: ipfspath.FromString(ipfspath.Join([]string{"/ipns", k.peerId}))}
 }
 
+// Generate generates new key, stores it in the keystore under the specified
+// name and returns a base58 encoded multihash of its public key.
 func (api *KeyAPI) Generate(ctx context.Context, name string, opts ...caopts.KeyGenerateOption) (coreiface.Key, error) {
 	options, err := caopts.KeyGenerateOptions(opts...)
 	if err != nil {
@@ -88,6 +92,7 @@ func (api *KeyAPI) Generate(ctx context.Context, name string, opts ...caopts.Key
 	return &key{name, pid.Pretty()}, nil
 }
 
+// List returns a list keys stored in keystore.
 func (api *KeyAPI) List(ctx context.Context) ([]coreiface.Key, error) {
 	keys, err := api.node.Repo.Keystore().List()
 	if err != nil {
@@ -117,6 +122,8 @@ func (api *KeyAPI) List(ctx context.Context) ([]coreiface.Key, error) {
 	return out, nil
 }
 
+// Rename renames `oldName` to `newName`. Returns the key and whether another
+// key was overwritten, or an error.
 func (api *KeyAPI) Rename(ctx context.Context, oldName string, newName string, opts ...caopts.KeyRenameOption) (coreiface.Key, bool, error) {
 	options, err := caopts.KeyRenameOptions(opts...)
 	if err != nil {
@@ -169,6 +176,7 @@ func (api *KeyAPI) Rename(ctx context.Context, oldName string, newName string, o
 	return &key{newName, pid.Pretty()}, overwrite, ks.Delete(oldName)
 }
 
+// Remove removes keys from keystore. Returns ipns path of the removed key.
 func (api *KeyAPI) Remove(ctx context.Context, name string) (coreiface.Path, error) {
 	ks := api.node.Repo.Keystore()
 

core/coreapi/name.go

@@ -29,14 +29,17 @@ type ipnsEntry struct {
 	value coreiface.Path
 }
 
+// Name returns the ipnsEntry name.
 func (e *ipnsEntry) Name() string {
 	return e.name
 }
 
+// Value returns the ipnsEntry value.
 func (e *ipnsEntry) Value() coreiface.Path {
 	return e.value
 }
 
+// Publish announces new IPNS name and returns the new IPNS entry.
 func (api *NameAPI) Publish(ctx context.Context, p coreiface.Path, opts ...caopts.NamePublishOption) (coreiface.IpnsEntry, error) {
 	options, err := caopts.NamePublishOptions(opts...)
 	if err != nil {
@@ -82,6 +85,8 @@ func (api *NameAPI) Publish(ctx context.Context, p coreiface.Path, opts ...caopt
 	}, nil
 }
 
+// Resolve attempts to resolve the newest version of the specified name and
+// returns its path.
 func (api *NameAPI) Resolve(ctx context.Context, name string, opts ...caopts.NameResolveOption) (coreiface.Path, error) {
 	options, err := caopts.NameResolveOptions(opts...)
 	if err != nil {

core/coreapi/unixfs.go

@@ -14,6 +14,8 @@ import (
 
 type UnixfsAPI CoreAPI
 
+// Add builds a merkledag node from a reader, adds it to the blockstore,
+// and returns the key representing that node.
 func (api *UnixfsAPI) Add(ctx context.Context, r io.Reader) (coreiface.Path, error) {
 	k, err := coreunix.AddWithContext(ctx, api.node, r)
 	if err != nil {
@@ -26,6 +28,7 @@ func (api *UnixfsAPI) Add(ctx context.Context, r io.Reader) (coreiface.Path, err
 	return ParseCid(c), nil
 }
 
+// Cat returns the data contained by an IPFS or IPNS object(s) at path `p`.
 func (api *UnixfsAPI) Cat(ctx context.Context, p coreiface.Path) (coreiface.Reader, error) {
 	dagnode, err := api.core().ResolveNode(ctx, p)
 	if err != nil {
@@ -41,6 +44,8 @@ func (api *UnixfsAPI) Cat(ctx context.Context, p coreiface.Path) (coreiface.Read
 	return r, nil
 }
 
+// Ls returns the contents of an IPFS or IPNS object(s) at path p, with the format:
+// `<link base58 hash> <link size in bytes> <link name>`
 func (api *UnixfsAPI) Ls(ctx context.Context, p coreiface.Path) ([]*coreiface.Link, error) {
 	dagnode, err := api.core().ResolveNode(ctx, p)
 	if err != nil {

core/coreunix/add.go

@@ -73,6 +73,7 @@ type AddedObject struct {
 	Size  string `json:",omitempty"`
 }
 
+// NewAdder Returns a new Adder used for a file add operation.
 func NewAdder(ctx context.Context, p pin.Pinner, bs bstore.GCBlockstore, ds dag.DAGService) (*Adder, error) {
 	return &Adder{
 		ctx:        ctx,
@@ -126,6 +127,7 @@ func (adder *Adder) mfsRoot() (*mfs.Root, error) {
 	return adder.mroot, nil
 }
 
+// SetMfsRoot sets `r` as the root for Adder.
 func (adder *Adder) SetMfsRoot(r *mfs.Root) {
 	adder.mroot = r
 }
@@ -152,6 +154,7 @@ func (adder *Adder) add(reader io.Reader) (node.Node, error) {
 	return balanced.BalancedLayout(params.New(chnk))
 }
 
+// RootNode returns the root node of the Added.
 func (adder *Adder) RootNode() (node.Node, error) {
 	// for memoizing
 	if adder.root != nil {
@@ -181,6 +184,8 @@ func (adder *Adder) RootNode() (node.Node, error) {
 	return root, err
 }
 
+// Recursively pins the root node of Adder and
+// writes the pin state to the backing datastore.
 func (adder *Adder) PinRoot() error {
 	root, err := adder.RootNode()
 	if err != nil {
@@ -207,6 +212,7 @@ func (adder *Adder) PinRoot() error {
 	return adder.pinning.Flush()
 }
 
+// Finalize flushes the mfs root directory and returns the mfs root node.
 func (adder *Adder) Finalize() (node.Node, error) {
 	mr, err := adder.mfsRoot()
 	if err != nil {
@@ -566,6 +572,7 @@ func outputDagnode(out chan interface{}, name string, dn node.Node) error {
 	return nil
 }
 
+// NewMemoryDagService builds and returns a new mem-datastore.
 func NewMemoryDagService() dag.DAGService {
 	// build mem-datastore for editor's intermediary nodes
 	bs := bstore.NewBlockstore(syncds.MutexWrap(ds.NewMapDatastore()))