coreapi: Documentation for Name/Key

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

core/coreapi/coreapi.go

@@ -26,17 +26,11 @@ func (api *CoreAPI) Unixfs() coreiface.UnixfsAPI {
 }
 
 func (api *CoreAPI) Name() coreiface.NameAPI {
-	return &NameAPI{
-		api,
-		nil,
-	}
+	return &NameAPI{api, nil}
 }
 
 func (api *CoreAPI) Key() coreiface.KeyAPI {
-	return &KeyAPI{
-		api,
-		nil,
-	}
+	return &KeyAPI{api, nil}
 }
 
 func (api *CoreAPI) ResolveNode(ctx context.Context, p coreiface.Path) (coreiface.Node, error) {

core/coreapi/interface/interface.go

@@ -65,26 +65,73 @@ type UnixfsAPI interface {
 	Ls(context.Context, Path) ([]*Link, error)
 }
 
+// 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)
 }
 

core/coreapi/key.go

@@ -30,7 +30,7 @@ func (api *KeyAPI) Generate(ctx context.Context, name string, opts ...caopts.Key
 	switch options.Algorithm {
 	case "rsa":
 		if options.Size == 0 {
-			return "", fmt.Errorf("please specify a key size with --size")
+			return "", fmt.Errorf("please specify a key size with WithSize option")
 		}
 
 		priv, pub, err := crypto.GenerateKeyPairWithReader(crypto.RSA, options.Size, rand.Reader)