Merge pull request #10 from Mr0grog/docs/9-add-readme-usage

Add usage section to README

README.md

@@ -8,8 +8,39 @@
 
 > ipns record definitions
 
-This package contains all of components necessary to create, understand, and
-validate IPNS records.
+This package contains all of components necessary to create, understand, and validate IPNS records. It does *not* publish or resolve those records. [`go-ipfs`](https://github.com/ipfs/go-ipfs) uses this package internally to manipulate records.
+
+## Usage
+
+To create a new IPNS record:
+
+```go
+import (
+	"time"
+
+	ipns "github.com/ipfs/go-ipns"
+	crypto "github.com/libp2p/go-libp2p-crypto"
+)
+
+// Generate a private key to sign the IPNS record with. Most of the time, 
+// however, you'll want to retrieve an already-existing key from IPFS using the
+// go-ipfs/core/coreapi CoreAPI.KeyAPI() interface.
+privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.RSA, 2048)
+if err != nil {
+  panic(err)
+}
+
+// Create an IPNS record that expires in one hour and points to the IPFS address
+// /ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5
+ipnsRecord, err := ipns.Create(privateKey, []byte("/ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5"), 0, time.Now().Add(1*time.Hour))
+if err != nil {
+	panic(err)
+}
+```
+
+Once you have the record, you’ll need to use IPFS to *publish* it.
+
+There are several other major operations you can do with `go-ipns`. Check out the [API docs](https://godoc.org/github.com/ipfs/go-ipns) or look at the tests in this repo for examples.
 
 ## Documentation
 

ipns_test.go

 package ipns
 
 import (
+	"fmt"
 	"testing"
 	"time"
 
@@ -41,3 +42,22 @@ func TestEmbedPublicKey(t *testing.T) {
 		t.Fatalf("pid mismatch: %s != %s", pid, embeddedPid)
 	}
 }
+
+func ExampleCreate() {
+	// Generate a private key to sign the IPNS record with. Most of the time,
+	// however, you'll want to retrieve an already-existing key from IPFS using
+	// go-ipfs/core/coreapi CoreAPI.KeyAPI() interface.
+	privateKey, _, err := ci.GenerateKeyPair(ci.RSA, 2048)
+	if err != nil {
+		panic(err)
+	}
+
+	// Create an IPNS record that expires in one hour and points to the IPFS address
+	// /ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5
+	ipnsRecord, err := Create(privateKey, []byte("/ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5"), 0, time.Now().Add(1*time.Hour))
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(ipnsRecord)
+}