From 953d363b3a50a1ee9d5c98da0d50e338b66a11c5 Mon Sep 17 00:00:00 2001
From: saxon <saxon.milton@gmail.com>
Date: Mon, 4 Feb 2019 22:38:11 +1030
Subject: [PATCH] stream/mts/meta.go: improved const and function commenting

---
 stream/mts/meta/meta.go | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/stream/mts/meta/meta.go b/stream/mts/meta/meta.go
index 2f26a797..1e4c72b8 100644
--- a/stream/mts/meta/meta.go
+++ b/stream/mts/meta/meta.go
@@ -33,6 +33,8 @@ import (
 	"sync"
 )
 
+// This is the headsize of our metadata string,
+// which is encoded int the data body of a pmt descriptor.
 const headSize = 4
 
 const (
@@ -40,6 +42,7 @@ const (
 	minVer = 0
 )
 
+// Indices of bytes for uint16 metadata length.
 const (
 	dataLenIdx1 = 2
 	dataLenIdx2 = 3
@@ -49,12 +52,15 @@ var (
 	errKeyAbsent = errors.New("Key does not exist in map")
 )
 
+// Metadata provides functionality for the storage and encoding of metadata
+// using a map.
 type Metadata struct {
 	mu   sync.RWMutex
 	data map[string]string
 	enc  []byte
 }
 
+// New returns a pointer to a new Metadata.
 func New() *Metadata {
 	return &Metadata{
 		data: make(map[string]string),
@@ -67,14 +73,14 @@ func New() *Metadata {
 	}
 }
 
-// Add adds metadata with key and val
+// Add adds metadata with key and val.
 func (m *Metadata) Add(key, val string) {
 	m.mu.Lock()
 	m.data[key] = val
 	m.mu.Unlock()
 }
 
-// All returns the a copy of the map containing the meta data
+// All returns the a copy of the map containing the meta data.
 func (m *Metadata) All() map[string]string {
 	m.mu.Lock()
 	cpy := make(map[string]string)
@@ -85,7 +91,7 @@ func (m *Metadata) All() map[string]string {
 	return cpy
 }
 
-// Get returns the meta data for the passed key
+// Get returns the meta data for the passed key.
 func (m *Metadata) Get(key string) (string, error) {
 	m.mu.Lock()
 	val, ok := m.data[key]
@@ -93,11 +99,10 @@ func (m *Metadata) Get(key string) (string, error) {
 	if !ok {
 		return "", errKeyAbsent
 	}
-
 	return val, nil
 }
 
-// Remove deletes a meta entry in the map and returns error if it doesn’t exist
+// Delete deletes a meta entry in the map and returns error if it doesn’t exist.
 func (m *Metadata) Delete(key string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -108,12 +113,13 @@ func (m *Metadata) Delete(key string) error {
 	return errKeyAbsent
 }
 
-// Encode takes the meta data map and encods into a byte slice with header
+// Encode takes the meta data map and encodes into a byte slice with header
 // describing the version, length of data and data in TSV format.
 func (m *Metadata) Encode() []byte {
 	m.enc = m.enc[:headSize]
 
-	// Iterate over map and append entries, only adding tab if we're not on the last entry
+	// Iterate over map and append entries, only adding tab if we're not on the
+	// last entry.
 	var i int
 	var entry string
 	for k, v := range m.data {
@@ -133,6 +139,9 @@ func (m *Metadata) Encode() []byte {
 	return m.enc
 }
 
+// ReadFrom extracts a value from a metadata string d, for the given key. If the
+// key is not present in the metadata string, an error is returned. If the
+// metadata header is not present in the string, an error is returned.
 func ReadFrom(d []byte, key string) (string, error) {
 	entries := strings.Split(string(d), "\t")
 	for _, entry := range entries {
@@ -141,5 +150,5 @@ func ReadFrom(d []byte, key string) (string, error) {
 			return kv[1], nil
 		}
 	}
-	return "", errors.New("could not find key in metadata")
+	return "", errKeyAbsent
 }