From 4a0c98e9d45706d0d6f15ad285f787320e0ef87c Mon Sep 17 00:00:00 2001
From: Sam Woodard <sam.h.woodard@gmail.com>
Date: Tue, 16 Oct 2018 07:34:22 -0700
Subject: [PATCH] add docs for runtime.go

---
 runtime.go | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/runtime.go b/runtime.go
index 7dc6581..db2d9f2 100644
--- a/runtime.go
+++ b/runtime.go
@@ -8,35 +8,58 @@ import (
 	"time"
 )
 
+// Event represents a lifecycle event in the marshaling or unmarshalling
+// process.
 type Event int
 
 const (
+	// UnmarshalStart is the Event that is sent when deserialization of a payload
+	// begins.
 	UnmarshalStart Event = iota
+
+	// UnmarshalStop is the Event that is sent when deserialization of a payload
+	// ends.
 	UnmarshalStop
+
+	// MarshalStart is the Event that is sent sent when serialization of a payload
+	// begins.
 	MarshalStart
+
+	// MarshalStop is the Event that is sent sent when serialization of a payload
+	// ends.
 	MarshalStop
 )
 
+// Runtime has the same methods as jsonapi package for serialization and
+// deserialization but also has a ctx, a map[string]interface{} for storing
+// state, designed for instrumenting serialization timings.
 type Runtime struct {
 	ctx map[string]interface{}
 }
 
+// Events is the func type that provides the callback for handling event timings.
 type Events func(*Runtime, Event, string, time.Duration)
 
+// Instrumentation is a a global Events variable.  This is the handler for all
+// timing events.
 var Instrumentation Events
 
+// NewRuntime creates a Runtime for use in an application.
 func NewRuntime() *Runtime { return &Runtime{make(map[string]interface{})} }
 
+// WithValue adds custom state variables to the runtime context.
 func (r *Runtime) WithValue(key string, value interface{}) *Runtime {
 	r.ctx[key] = value
 
 	return r
 }
 
+// Value returns a state variable in the runtime context.
 func (r *Runtime) Value(key string) interface{} {
 	return r.ctx[key]
 }
 
+// Instrument is deprecated.
 func (r *Runtime) Instrument(key string) *Runtime {
 	return r.WithValue("instrument", key)
 }
@@ -45,12 +68,14 @@ func (r *Runtime) shouldInstrument() bool {
 	return Instrumentation != nil
 }
 
+// UnmarshalPayload has docs in request.go for UnmarshalPayload.
 func (r *Runtime) UnmarshalPayload(reader io.Reader, model interface{}) error {
 	return r.instrumentCall(UnmarshalStart, UnmarshalStop, func() error {
 		return UnmarshalPayload(reader, model)
 	})
 }
 
+// UnmarshalManyPayload has docs in request.go for UnmarshalManyPayload.
 func (r *Runtime) UnmarshalManyPayload(reader io.Reader, kind reflect.Type) (elems []interface{}, err error) {
 	r.instrumentCall(UnmarshalStart, UnmarshalStop, func() error {
 		elems, err = UnmarshalManyPayload(reader, kind)
@@ -60,6 +85,7 @@ func (r *Runtime) UnmarshalManyPayload(reader io.Reader, kind reflect.Type) (ele
 	return
 }
 
+// MarshalPayload has docs in response.go for MarshalPayload.
 func (r *Runtime) MarshalPayload(w io.Writer, model interface{}) error {
 	return r.instrumentCall(MarshalStart, MarshalStop, func() error {
 		return MarshalPayload(w, model)