[v4] improve metadata documentation (#216)

* add usage docs for context types and metadata, improve comments

* changes after review

metadata/iterator.go

@@ -0,0 +1,37 @@
+package metadata
+
+import "sort"
+
+type Iterator struct {
+	md   Metadata
+	keys []string
+	cur  int
+	cnt  int
+}
+
+// Next advances the iterator to the next element.
+func (iter *Iterator) Next(k *string, v *[]string) bool {
+	if iter.cur+1 > iter.cnt {
+		return false
+	}
+
+	if k != nil && v != nil {
+		*k = iter.keys[iter.cur]
+		vv := iter.md[*k]
+		*v = make([]string, len(vv))
+		copy(*v, vv)
+		iter.cur++
+	}
+	return true
+}
+
+// Iterator returns an iterator for iterating over metadata in sorted order.
+func (md Metadata) Iterator() *Iterator {
+	iter := &Iterator{md: md, cnt: len(md)}
+	iter.keys = make([]string, 0, iter.cnt)
+	for k := range md {
+		iter.keys = append(iter.keys, k)
+	}
+	sort.Strings(iter.keys)
+	return iter
+}