From 0913011f75a1be9a03ac9124eedae5813a5eb06e Mon Sep 17 00:00:00 2001
From: Roger Guldbrandsen <roger@kinbiko.com>
Date: Fri, 1 Feb 2019 22:08:07 +0000
Subject: [PATCH] Improve godocs for exported code

---
 exports.go | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/exports.go b/exports.go
index 5e1144d..d42b0b2 100644
--- a/exports.go
+++ b/exports.go
@@ -4,23 +4,25 @@ import (
 	"fmt"
 )
 
-// Printer is any interface that has a testing.T-like Errorf function.
-// Most users probably want to pass in a *testing.T instance here.
+// Printer is any type that has a testing.T-like Errorf function.
+// You probably want to pass in a *testing.T instance here if you are using
+// this in your tests.
 type Printer interface {
 	Errorf(msg string, args ...interface{})
 }
 
-// Asserter represents the main type of jsonassert.
-// See Asserter.Assert for the main use of this package.
+// Asserter represents the main type within the jsonassert package.
+// See Asserter.Assertf for the main use of this package.
 type Asserter struct {
 	Printer Printer
 }
 
-// New creates a new Asserter for making assertions against JSON.
-// Can be reused. I.e. if you are using jsonassert as part of your tests,
-// you only need one jsonassert.Asseter per test, which can be re-used in sub-tests.
+// New creates a new *jsonassert.Asserter for making assertions against JSON payloads.
+// This type can be reused. I.e. if you are using jsonassert as part of your tests,
+// you only need one *jsonassert.Asseter per (sub)test.
 // In most cases, this will look something like
-// ja := jsonassert.New(t) // t is an instance of *testing.T
+//
+// ja := jsonassert.New(t)
 func New(p Printer) *Asserter {
 	return &Asserter{Printer: p}
 }
@@ -29,16 +31,25 @@ func New(p Printer) *Asserter {
 // make assertions against. The second string is the 'expected' JSON, which
 // can be treated as a template for additional format arguments.
 // If any discrepancies are found, these will be given to the Errorf function in the printer.
-// E.g. for the JSON {"hello": "world"}, you may use an expected JSON of
-// {"hello": "%s"}, along with the "world" format argument.
-// For example:
+// E.g. for the JSON
+//
+// {"hello": "world"}
+//
+// you may use an expected JSON of
+//
+// {"hello": "%s"}
+//
+// along with the "world" format argument. For example:
+//
 // ja.Assertf(`{"hello": "world"}`, `{"hello":"%s"}`, "world")
 //
-// Additionally, you may wish to make assertions against the *presence* of a value, but
-// For example:
-// ja.Assertf(`{"uuid": "94ae1a31-63b2-4a55-a478-47764b60c56b"}`, `{"hello":"<<PRESENCE>>"}`)
+// Additionally, you may wish to make assertions against the *presence* of a
+// value, but not against its value. For example:
+//
+// ja.Assertf(`{"uuid": "94ae1a31-63b2-4a55-a478-47764b60c56b"}`, `{"uuid":"<<PRESENCE>>"}`)
+//
 // will verify that the UUID field is present, but does not check its actual value.
-// You may use "<<PRESENCE>>" against any type of value. The exception is null, which
+// You may use "<<PRESENCE>>" against any type of value. The only exception is null, which
 // will result in an assertion failure.
 func (a *Asserter) Assertf(actualJSON, expectedJSON string, fmtArgs ...interface{}) {
 	a.pathassertf("$", actualJSON, fmt.Sprintf(expectedJSON, fmtArgs...))