[docs] Clarify SetURLVars

[fharding1]

Clarify in documentation that SetURLVars does not modify the given *htttp.Request, provide an example of usage.

Addresses #334

[kisielk]

Can you make the example a runnable example test? The function doc can be shorter, just "... does not modify its arguments, but returns a shallow copy..", it should be obvious that it can be assigned to something.

[fharding1]

Sure! Just to clarify, would you want me to include package, imports, etc, or just the relevant parts, like

package example

import (
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/gorilla/mux"
	"github.com/stretchr/testify/assert"
)

const (
	varKey   = "foo"
	varValue = "bar"
)

func ExampleHandler(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte(mux.Vars(r)[varKey]))
}

func TestExample(t *testing.T) {
	req, _ := http.NewRequest("GET", "/foo", nil)
	req = mux.SetURLVars(req, map[string]string{varKey: varValue})
	rr := httptest.NewRecorder()

	ExampleHandler(rr, req)

	assert.Equal(t, varValue, string(rr.Body.Bytes()))
}

vs

const (
	varKey   = "foo"
	varValue = "bar"
)

func ExampleHandler(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte(mux.Vars(r)[varKey]))
}

func TestExample(t *testing.T) {
	req, _ := http.NewRequest("GET", "/foo", nil)
	req = mux.SetURLVars(req, map[string]string{varKey: varValue})
	rr := httptest.NewRecorder()

	ExampleHandler(rr, req)

	assert.Equal(t, varValue, string(rr.Body.Bytes()))
}

[kisielk]

Make a function in one of the test files called ExampleSetURLVars and put the whole example in there. That will show up in the documentation alongside the SetURLVars function. More details in the "Examples" section here: https://godoc.org/testing

[fharding1]

Added. It's my first time using example test functions, so I apologize if I messed up.