docs: update README

1. add install instructions
2. add examples
3. add build instructions
4. add instructions to run tests and benchmarks
5. add contributing instructions
6. add pointer to license

README.md

@@ -1 +1,151 @@
 # did
+
+`did` is a Go package that provides tools to work with
+[Decentralized Identifiers (DIDs)](https://w3c-ccg.github.io/did-spec).
+
+## Install
+
+```
+go get github.com/ockam-network/did
+```
+
+## Example
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/ockam-network/did"
+)
+
+func main() {
+  d, err := did.Parse("did:example:q7ckgxeq1lxmra0r")
+  if err != nil {
+    log.Fatal(err)
+  }
+  fmt.Printf("%#v", d)
+}
+```
+
+The above example parses the input string according to the rules defined in the [DID Grammar](did.abnf) and prints the
+following value of DID type.
+
+```go
+&did.DID{
+  Method:"example",
+  ID:"q7ckgxeq1lxmra0r",
+  IDStrings:[]string{"q7ckgxeq1lxmra0r"},
+  Path:"",
+  PathSegments:[]string(nil),
+  Fragment:""
+}
+```
+
+The input string may also be a [DID Reference](https://w3c-ccg.github.io/did-spec/#dfn-did-reference) with a
+[DID Path](https://w3c-ccg.github.io/did-spec/#dfn-did-path):
+
+```go
+d, err := did.Parse("did:example:q7ckgxeq1lxmra0r/abc/pqr")
+```
+
+which would result in:
+
+```go
+&did.DID{
+  Method:"example",
+  ID:"q7ckgxeq1lxmra0r",
+  IDStrings:[]string{"q7ckgxeq1lxmra0r"},
+  Path:"abc/pqr",
+  PathSegments:[]string{"abc", "pqr"},
+  Fragment:""
+}
+```
+
+or a [DID Reference](https://w3c-ccg.github.io/did-spec/#dfn-did-reference) with a
+[DID Fragment](https://w3c-ccg.github.io/did-spec/#dfn-did-fragment):
+
+```go
+d, err := did.Parse("did:example:q7ckgxeq1lxmra0r#keys-1")
+fmt.Println(d.Fragment)
+// Output: keys-1
+```
+
+This package also implements the [Stringer](https://golang.org/pkg/fmt/#Stringer) interface for the DID type. It is
+easy to convert DID type structures into valid DID strings:
+
+```go
+d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r"}
+fmt.Println(d.String())
+// Output: did:example:q7ckgxeq1lxmra0r
+```
+
+or with a refence with a fragment:
+
+```go
+d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Fragment: "keys-1"}
+fmt.Println(d.String())
+// Output: did:example:q7ckgxeq1lxmra0r#keys-1
+```
+
+For more documentation and examples, please see godoc.
+
+## Build
+
+To compile the code in this repository, run:
+
+```
+go build
+```
+
+## Test
+
+This repository includes a comprehensive [suite of tests](did_test.go) that check for various edge cases within
+the [DID Grammar](did.abnf).
+
+To run the tests, run:
+
+```
+go test -v -cover
+```
+
+## Benchmark
+
+We haven't spent any time tuning the performance of the parser, however this repository includes some
+[benchmarks](benchmark_test.go) that compare the speed of `did.Parse` against Go's `url.Parse` with inputs
+of similar length, this is intended as a sanity check to ensure that `did.Parse` is at least comparable in performance
+to `url.Parse`
+
+```
+go test -bench=.
+```
+
+`did.Parse` included in this package:
+
+```
+BenchmarkParse-8                  	 5000000	       345 ns/op
+BenchmarkParseWithPath-8          	 3000000	       477 ns/op
+BenchmarkParseWithFragment-8      	 3000000	       542 ns/op
+```
+
+Go's `url.Parse`:
+
+```
+BenchmarkUrlParse-8               	 3000000	       574 ns/op
+BenchmarkUrlParseWithPath-8       	 3000000	       514 ns/op
+BenchmarkUrlParseWithFragment-8   	 5000000	       382 ns/op
+```
+
+## Contributing
+
+This package is early in its development and we welcome all contributions from the DID community. Please open issues
+and send pull requests.
+
+We follow the conventions specified in [Conventional Commits](https://www.conventionalcommits.org/) for our commit
+messages.
+
+## License
+
+This package is licensed under [Apache License 2.0](LICENSE).