From b92cca8429acecf498e37fd438df15a323e4c246 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Magiera?= <magik6k@gmail.com>
Date: Fri, 15 Dec 2017 01:03:53 +0100
Subject: [PATCH] coreapi: Documentation for Name/Key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

License: MIT
Signed-off-by: Łukasz Magiera <magik6k@gmail.com>


This commit was moved from ipfs/interface-go-ipfs-core@74695ab9b4f2efc64b6a88fcd900fbd67a63b416

This commit was moved from ipfs/boxo@d733fa263ca5d8340684f8c062ef474000f54fe7
---
 core/coreiface/interface.go | 47 +++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go
index 36bd801a1..a861e4700 100644
--- a/core/coreiface/interface.go
+++ b/core/coreiface/interface.go
@@ -98,26 +98,73 @@ type DagAPI interface {
 	WithDepth(depth int) options.DagTreeOption
 }
 
+// NameAPI specifies the interface to IPNS.
+//
+// IPNS is a PKI namespace, where names are the hashes of public keys, and the
+// private key enables publishing new (signed) values. In both publish and
+// resolve, the default name used is the node's own PeerID, which is the hash of
+// its public key.
+//
+// You can use .Key API to list and generate more names and their respective keys.
 type NameAPI interface {
+	// Publish announces new IPNS name
 	Publish(ctx context.Context, path Path, opts ...options.NamePublishOption) (*IpnsEntry, error)
+
+	// WithValidTime is an option for Publish which specifies for how long the
+	// entry will remain valid. Default value is 24h
 	WithValidTime(validTime time.Duration) options.NamePublishOption
+
+	// WithKey is an option for Publish which specifies the key to use for
+	// publishing. Default value is "self" which is the node's own PeerID.
+	//
+	// You can use .Key API to list and generate more names and their respective keys.
 	WithKey(key string) options.NamePublishOption
 
+	// Resolve attempts to resolve the newest version of the specified name
 	Resolve(ctx context.Context, name string, opts ...options.NameResolveOption) (Path, error)
+
+	// WithRecursive is an option for Resolve which specifies whether to perform a
+	// recursive lookup. Default value is false
 	WithRecursive(recursive bool) options.NameResolveOption
+
+	// WithLocal is an option for Resolve which specifies if the lookup should be
+	// offline. Default value is false
 	WithLocal(local bool) options.NameResolveOption
+
+	// WithNoCache is an option for Resolve which specifies when set to true
+	// disables the use of local name cache. Default value is false
 	WithNoCache(nocache bool) options.NameResolveOption
 }
 
+// KeyAPI specifies the interface to Keystore
 type KeyAPI interface {
+	// Generate generates new key, stores it in the keystore under the specified
+	// name and returns a base58 encoded multihash of it's public key
 	Generate(ctx context.Context, name string, opts ...options.KeyGenerateOption) (string, error)
+
+	// WithAlgorithm is an option for Generate which specifies which algorithm
+	// should be used for the key. Default is "rsa"
+	//
+	// Supported algorithms:
+	// * rsa
+	// * ed25519
 	WithAlgorithm(algorithm string) options.KeyGenerateOption
+
+	// WithSize is an option for Generate which specifies the size of the key to
+	// generated. Default is 0
 	WithSize(size int) options.KeyGenerateOption
 
+	// Rename renames oldName key to newName.
 	Rename(ctx context.Context, oldName string, newName string, opts ...options.KeyRenameOption) (string, bool, error)
+
+	// WithForce is an option for Rename which specifies whether to allow to
+	// replace existing keys.
 	WithForce(force bool) options.KeyRenameOption
 
+	// List lists keys stored in keystore
 	List(ctx context.Context) (map[string]string, error) //TODO: better key type?
+
+	// Remove removes keys from keystore
 	Remove(ctx context.Context, name string) (string, error)
 }