[doc] Add more detail to Schemes and URL godocs

route.go

@@ -430,6 +430,12 @@ func (m schemeMatcher) Match(r *http.Request, match *RouteMatch) bool {
 
 // Schemes adds a matcher for URL schemes.
 // It accepts a sequence of schemes to be matched, e.g.: "http", "https".
+// If the request's URL has a scheme set, it will be matched against.
+// Generally, the URL scheme will only be set if a previous handler set it,
+// such as the ProxyHeaders handler from gorilla/handlers.
+// If unset, the scheme will be determined based on the request's TLS
+// termination state.
+// The first argument to Schemes will be used when constructing a route URL.
 func (r *Route) Schemes(schemes ...string) *Route {
 	for k, v := range schemes {
 		schemes[k] = strings.ToLower(v)
@@ -506,8 +512,8 @@ func (r *Route) Subrouter() *Router {
 // This also works for host variables:
 //
 //     r := mux.NewRouter()
-//     r.Host("{subdomain}.domain.com").
-//       HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler).
+//     r.HandleFunc("/articles/{category}/{id:[0-9]+}", ArticleHandler).
+//       Host("{subdomain}.domain.com").
 //       Name("article")
 //
 //     // url.String() will be "http://news.domain.com/articles/technology/42"
@@ -515,6 +521,13 @@ func (r *Route) Subrouter() *Router {
 //                                      "category", "technology",
 //                                      "id", "42")
 //
+// The scheme of the resulting url will be the first argument that was passed to Schemes:
+//
+//     // url.String() will be "https://example.com"
+//     r := mux.NewRouter()
+//     url, err := r.Host("example.com")
+//                  .Schemes("https", "http").URL()
+//
 // All variables defined in the route are required, and their values must
 // conform to the corresponding patterns.
 func (r *Route) URL(pairs ...string) (*url.URL, error) {