Complete documentation; deprecate AllowOriginRequestFunc in favour of…

… AllowOriginVaryRequestFunc (#169)

* Fix minor grammatical mistakes

* Document AllowOriginVaryRequestFunc in the README

* Document AllowPrivateNetwork in README

* Mark AllowOriginRequestFunc as deprecated

README.md

@@ -88,11 +88,14 @@ handler = c.Handler(handler)
 
 * **AllowedOrigins** `[]string`: A list of origins a cross-domain request can be executed from. If the special `*` value is present in the list, all origins will be allowed. An origin may contain a wildcard (`*`) to replace 0 or more characters (i.e.: `http://*.domain.com`). Usage of wildcards implies a small performance penality. Only one wildcard can be used per origin. The default value is `*`.
 * **AllowOriginFunc** `func (origin string) bool`: A custom function to validate the origin. It takes the origin as an argument and returns true if allowed, or false otherwise. If this option is set, the content of `AllowedOrigins` is ignored.
-* **AllowOriginRequestFunc** `func (r *http.Request, origin string) bool`: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise. If this option is set, the content of `AllowedOrigins` and `AllowOriginFunc` is ignored
+* **AllowOriginRequestFunc** `func (r *http.Request, origin string) bool`: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise. If this option is set, the contents of `AllowedOrigins` and `AllowOriginFunc` are ignored.
+Deprecated: use `AllowOriginVaryRequestFunc` instead.
+* **AllowOriginVaryRequestFunc** `func(r *http.Request, origin string) (bool, []string)`: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise with a list of headers used to take that decision if any so they can be added to the Vary header. If this option is set, the contents of `AllowedOrigins`, `AllowOriginFunc` and `AllowOriginRequestFunc` are ignored.
 * **AllowedMethods** `[]string`: A list of methods the client is allowed to use with cross-domain requests. Default value is simple methods (`GET` and `POST`).
 * **AllowedHeaders** `[]string`: A list of non simple headers the client is allowed to use with cross-domain requests.
-* **ExposedHeaders** `[]string`: Indicates which headers are safe to expose to the API of a CORS API specification
+* **ExposedHeaders** `[]string`: Indicates which headers are safe to expose to the API of a CORS API specification.
 * **AllowCredentials** `bool`: Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates. The default is `false`.
+* **AllowPrivateNetwork** `bool`: Indicates whether to accept cross-origin requests over a private network.
 * **MaxAge** `int`: Indicates how long (in seconds) the results of a preflight request can be cached. The default is `0` which stands for no max age.
 * **OptionsPassthrough** `bool`: Instructs preflight to let other potential next handlers to process the `OPTIONS` method. Turn this on if your application handles `OPTIONS`.
 * **OptionsSuccessStatus** `int`: Provides a status code to use for successful OPTIONS requests. Default value is `http.StatusNoContent` (`204`).

cors.go

@@ -49,13 +49,15 @@ type Options struct {
 	// takes the HTTP Request object and the origin as argument and returns true
 	// if allowed or false otherwise. If headers are used take the decision,
 	// consider using AllowOriginVaryRequestFunc instead. If this option is set,
-	// the content of `AllowedOrigins`, `AllowOriginFunc` are ignored.
+	// the contents of `AllowedOrigins`, `AllowOriginFunc` are ignored.
+	//
+	// Deprecated: use `AllowOriginVaryRequestFunc` instead.
 	AllowOriginRequestFunc func(r *http.Request, origin string) bool
 	// AllowOriginVaryRequestFunc is a custom function to validate the origin.
 	// It takes the HTTP Request object and the origin as argument and returns
 	// true if allowed or false otherwise with a list of headers used to take
 	// that decision if any so they can be added to the Vary header. If this
-	// option is set, the content of `AllowedOrigins`, `AllowOriginFunc` and
+	// option is set, the contents of `AllowedOrigins`, `AllowOriginFunc` and
 	// `AllowOriginRequestFunc` are ignored.
 	AllowOriginVaryRequestFunc func(r *http.Request, origin string) (bool, []string)
 	// AllowedMethods is a list of methods the client is allowed to use with