godoc update

Author: jeevatkm

request.go

@@ -23,7 +23,7 @@ const (
 type (
 	// Request is extends `http.Request` for aah framework
 	Request struct {
-		// Schema value is protocol info; it's a derived value in the order as below.
+		// Scheme value is protocol; it's a derived value in the order as below.
 		//  - `X-Forwarded-Proto` is not empty return value as is
 		//  - `http.Request.TLS` is not nil value is `https`
 		//  - `http.Request.TLS` is nil value is `http`
@@ -41,24 +41,26 @@ type (
 		// Header request HTTP headers
 		Header http.Header
 
-		// Payload holds the value from HTTP request for `Content-Type`
-		// JSON and XML.
-		Payload []byte
-
-		// ContentType the parsed HTTP header `Content-Type`.
+		// ContentType the parsed value of HTTP header `Content-Type`.
+		// Partial implementation as per RFC1521.
 		ContentType *ContentType
 
 		// AcceptContentType negotiated value from HTTP Header `Accept`.
 		// The resolve order is-
 		// 1) URL extension
-		// 2) Accept header.
+		// 2) Accept header (As per RFC7231 and vendor type as per RFC4288)
 		// Most quailfied one based on quality factor otherwise default is HTML.
 		AcceptContentType *ContentType
 
 		// AcceptEncoding negotiated value from HTTP Header the `Accept-Encoding`
+		// As per RFC7231.
 		// Most quailfied one based on quality factor.
 		AcceptEncoding *AcceptSpec
 
+		// Payload holds the value from HTTP request for `Content-Type`
+		// JSON and XML.
+		Payload []byte
+
 		// Params contains values from Path, Query, Form and File.
 		Params *Params
 
@@ -68,10 +70,12 @@ type (
 		// UserAgent value of the HTTP 'User-Agent' header.
 		UserAgent string
 
-		// ClientIP remote client IP address.
+		// ClientIP remote client IP address aka Remote IP. Parsed in the order of
+		// `X-Forwarded-For`, `X-Real-IP` and finally `http.Request.RemoteAddr`.
 		ClientIP string
 
 		// Locale negotiated value from HTTP Header `Accept-Language`.
+		// As per RFC7231.
 		Locale *Locale
 
 		// IsGzipAccepted is true if the HTTP client accepts Gzip response,
@@ -131,7 +135,8 @@ func (r *Request) Cookies() []*http.Cookie {
 	return r.Raw.Cookies()
 }
 
-// IsJSONP method returns true if request query string has "callback=function_name".
+// IsJSONP method returns true if request URL query string has "callback=function_name".
+// otherwise false.
 func (r *Request) IsJSONP() bool {
 	return !ess.IsStrEmpty(r.QueryValue(jsonpReqParamKey))
 }
@@ -142,29 +147,31 @@ func (r *Request) IsAJAX() bool {
 	return r.Header.Get(HeaderXRequestedWith) == ajaxHeaderValue
 }
 
-// PathValue method return value for given Path param key otherwise empty string.
+// PathValue method returns value for given Path param key otherwise empty string.
+// For eg.: /users/:userId => PathValue("userId")
 func (r *Request) PathValue(key string) string {
 	return r.Params.PathValue(key)
 }
 
-// QueryValue method return value for given query (aka URL) param key
+// QueryValue method returns value for given URL query param key
 // otherwise empty string.
 func (r *Request) QueryValue(key string) string {
 	return r.Params.QueryValue(key)
 }
 
-// QueryArrayValue method return array value for given query (aka URL)
-// param key otherwise empty string.
+// QueryArrayValue method returns array value for given URL query param key
+// otherwise empty string slice.
 func (r *Request) QueryArrayValue(key string) []string {
 	return r.Params.QueryArrayValue(key)
 }
 
-// FormValue methos returns value for given form key otherwise empty string.
+// FormValue method returns value for given form key otherwise empty string.
 func (r *Request) FormValue(key string) string {
 	return r.Params.FormValue(key)
 }
 
-// FormArrayValue methos returns value for given form key otherwise empty string.
+// FormArrayValue method returns array value for given form key
+// otherwise empty string slice.
 func (r *Request) FormArrayValue(key string) []string {
 	return r.Params.FormArrayValue(key)
 }
@@ -182,10 +189,10 @@ func (r *Request) Reset() {
 	r.Method = ""
 	r.Path = ""
 	r.Header = nil
-	r.Payload = nil
 	r.ContentType = nil
 	r.AcceptContentType = nil
 	r.AcceptEncoding = nil
+	r.Payload = nil
 	r.Params = nil
 	r.Referer = ""
 	r.UserAgent = ""
@@ -199,7 +206,8 @@ func (r *Request) Reset() {
 // Params methods
 //___________________________________
 
-// PathValue method return value for given Path param key otherwise empty string.
+// PathValue method returns value for given Path param key otherwise empty string.
+// For eg.: `/users/:userId` => `PathValue("userId")`.
 func (p *Params) PathValue(key string) string {
 	if p.Path != nil {
 		if value, found := p.Path[key]; found {
@@ -209,30 +217,31 @@ func (p *Params) PathValue(key string) string {
 	return ""
 }
 
-// QueryValue method return value for given query (aka URL) param key
+// QueryValue method returns value for given URL query param key
 // otherwise empty string.
 func (p *Params) QueryValue(key string) string {
 	return p.Query.Get(key)
 }
 
-// QueryArrayValue method return array value for given query (aka URL)
-// param key otherwise empty string.
+// QueryArrayValue method returns array value for given URL query param key
+// otherwise empty string slice.
 func (p *Params) QueryArrayValue(key string) []string {
 	if values, found := p.Query[key]; found {
 		return values
 	}
 	return []string{}
 }
 
-// FormValue methos returns value for given form key otherwise empty string.
+// FormValue method returns value for given form key otherwise empty string.
 func (p *Params) FormValue(key string) string {
 	if p.Form != nil {
 		return p.Form.Get(key)
 	}
 	return ""
 }
 
-// FormArrayValue methos returns value for given form key otherwise empty string.
+// FormArrayValue method returns array value for given form key
+// otherwise empty string slice.
 func (p *Params) FormArrayValue(key string) []string {
 	if p.Form != nil {
 		if values, found := p.Form[key]; found {
@@ -242,8 +251,8 @@ func (p *Params) FormArrayValue(key string) []string {
 	return []string{}
 }
 
-// FormFile method returns the first file for the provided form key otherwise
-// returns error. It is caller responsibility to close the file.
+// FormFile method returns the first file for the provided form key
+// otherwise returns error. It is caller responsibility to close the file.
 func (p *Params) FormFile(key string) (multipart.File, *multipart.FileHeader, error) {
 	if p.File != nil {
 		if fh := p.File[key]; len(fh) > 0 {