add comments/documentation, change SingleHeaderMatcher -> HeaderMatcher

Author: cgilling

README.md

@@ -54,6 +54,20 @@ defer s.Close()
 downstream.AssertExpectations(t)
 ```
 
+If instead you wish to match against headers as well, a slightly different httpmock object can be used (please note the change in function name to be matched against):
+
+```go
+downstream := &httpmock.MockHandlerWithHeaders{}
+
+// A simple GET that returns some pre-canned content and a specific header
+downstream.On("HandleWithHeaders", "GET", "/object/12345", MatchHeader("MOCK", "this"), mock.Anything).Return(httpmock.Response{
+    Body: []byte(`{"status": "ok"}`),
+})
+
+// ... same as above
+
+```
+
 The httpmock package also provides helpers for checking calls using json objects, like so:
 
 ```go

httpmock.go

@@ -30,6 +30,19 @@ This example uses MockHandler, a Handler that is a github.com/stretchr/testify/m
 
 	downstream.AssertExpectations(t)
 
+If instead you wish to match against headers as well, a slightly different httpmock object can be used
+(please note the change in function name to be matched against):
+
+    downstream := &httpmock.MockHandlerWithHeaders{}
+
+    // A simple GET that returns some pre-canned content
+    downstream.On("HandleWithHeaders", "GET", "/object/12345", MatchHeader("MOCK", "this"), mock.Anything).Return(httpmock.Response{
+        Body: []byte(`{"status": "ok"}`),
+    })
+
+    // ... same as above
+
+
 Httpmock also provides helpers for checking calls using json objects, like so:
 
 	// This tests a hypothetical "echo" endpoint, which returns the body we pass to it.

httpmock_test.go

@@ -41,7 +41,7 @@ func TestBasicRequestResponseWithHeaders(t *testing.T) {
 		"HandleWithHeaders",
 		"GET",
 		"/object/12345",
-		SingleHeaderMatcher(headerKey, headerVal),
+		HeaderMatcher(headerKey, headerVal),
 		mock.Anything,
 	).
 		Return(Response{

mockhandler.go

@@ -64,12 +64,16 @@ func ToJSON(obj interface{}) []byte {
 	return data
 }
 
-func SingleHeaderMatcher(key, value string) interface{} {
+// HeaderMatcher matches the presence of a header named key that has a given value. Other headers
+// are allowed to exist and are not checked.
+func HeaderMatcher(key, value string) interface{} {
 	headers := make(http.Header)
 	headers.Set(key, value)
 	return MultiHeaderMatcher(headers)
 }
 
+// MultiHeaderMatcher matches the presence and content of multiple headers. Other headers besides those
+// within desiredHeaders are allowed to exist and are not checked.
 func MultiHeaderMatcher(desiredHeaders http.Header) interface{} {
 	return mock.MatchedBy(func(headers http.Header) bool {
 		for key, val := range desiredHeaders {