Merge pull request #10 from kinbiko/docs-improvements

Docs improvements

README.md

@@ -2,17 +2,11 @@
 
 [![Build Status](https://travis-ci.com/kinbiko/jsonassert.svg?branch=master)](https://travis-ci.com/kinbiko/jsonassert)
 
-`jsonassert` is a Go test assertion library for asserting JSON payloads.
-
-## Installation
-
-```bash
-go get github.com/kinbiko/jsonassert
-```
+`jsonassert` is a Go test assertion library for verifying that two representations of JSON are semantically equal.
 
 ## Usage
 
-Create a new `jsonassert.Asserter` in your test and use this to make assertions against your JSON payloads:
+Create a new `*jsonassert.Asserter` in your test and use this to make assertions against your JSON payloads:
 
 ```go
 func TestWhatever(t *testing.T) {
@@ -31,16 +25,16 @@ func TestWhatever(t *testing.T) {
 }
 ```
 
-Notice that you can pass in `fmt.Sprintf` arguments after the expected JSON structure.
+You may pass in `fmt.Sprintf` arguments after the expected JSON structure.
 
-`Asserter.Assertf()` currently supports assertions against strings only.
+`ja.Assertf()` currently supports assertions against **strings only**.
 
 ### Check for presence only
 
 Some properties of a JSON payload may be difficult to know in advance.
 E.g. timestamps, UUIDs, or other randomly assigned values.
 
-For these types of values, place the string `"<<PRESENCE>>"` as the expected value, and `jsonassert` will only verify that this key exists (i.e. the actual JSON has the expected key, and its value is not `null`), but not check it's value.
+For these types of values, place the string `"<<PRESENCE>>"` as the expected value, and `jsonassert` will only verify that this key exists (i.e. the actual JSON has the expected key, and its value is not `null`), but this does not check its value.
 
 For example:
 
@@ -60,7 +54,7 @@ func TestWhatever(t *testing.T) {
 }
 ```
 
-The above will fail your test, but:
+The above will pass your test, but:
 
 ```go
 func TestWhatever(t *testing.T) {

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...))