From 8ca2a65629418f0e78db70e8ac90b9884286c856 Mon Sep 17 00:00:00 2001
From: roc <roc@imroc.cc>
Date: Mon, 31 Jul 2023 17:37:54 +0800
Subject: [PATCH] add comments

---
 client.go    | 21 +++++++++++++++++++++
 request.go   | 33 ++++++++++++++++++++++++++++-----
 transport.go | 19 +++++++++++++++++++
 3 files changed, 68 insertions(+), 5 deletions(-)

diff --git a/client.go b/client.go
index b05411ee..9cd56774 100644
--- a/client.go
+++ b/client.go
@@ -871,11 +871,32 @@ func (c *Client) SetCommonHeadersNonCanonical(hdrs map[string]string) *Client {
 	return c
 }
 
+// SetCommonHeaderOrder set the order of the http header requests fired from the
+// client (case-insensitive).
+// For example:
+//
+//	client.R().SetCommonHeaderOrder(
+//	    "custom-header",
+//	    "cookie",
+//	    "user-agent",
+//	    "accept-encoding",
+//	).Get(url
 func (c *Client) SetCommonHeaderOrder(keys ...string) *Client {
 	c.t.SetHeaderOrder(keys...)
 	return c
 }
 
+// SetCommonPseudoHeaderOder set the order of the pseudo http header requests fired
+// from the client (case-insensitive).
+// Note this is only valid for http2 and http3.
+// For example:
+//
+//	client.SetCommonPseudoHeaderOder(
+//	    ":scheme",
+//	    ":authority",
+//	    ":path",
+//	    ":method",
+//	)
 func (c *Client) SetCommonPseudoHeaderOder(keys ...string) *Client {
 	c.t.SetPseudoHeaderOder(keys...)
 	return c
diff --git a/request.go b/request.go
index 7e705bb6..d0a295a5 100644
--- a/request.go
+++ b/request.go
@@ -464,10 +464,23 @@ func (r *Request) SetHeaderNonCanonical(key, value string) *Request {
 }
 
 const (
-	HeaderOderKey       = "__header_order__"
+	// HeaderOderKey is the key of header order, which specifies the order
+	// of the http header.
+	HeaderOderKey = "__header_order__"
+	// PseudoHeaderOderKey is the key of pseudo header order, which specifies
+	// the order of the http2 and http3 pseudo header.
 	PseudoHeaderOderKey = "__pseudo_header_order__"
 )
 
+// SetHeaderOrder set the order of the http header (case-insensitive).
+// For example:
+//
+//	client.R().SetHeaderOrder(
+//	    "custom-header",
+//	    "cookie",
+//	    "user-agent",
+//	    "accept-encoding",
+//	).Get(url)
 func (r *Request) SetHeaderOrder(keys ...string) *Request {
 	if r.Headers == nil {
 		r.Headers = make(http.Header)
@@ -476,6 +489,16 @@ func (r *Request) SetHeaderOrder(keys ...string) *Request {
 	return r
 }
 
+// SetPseudoHeaderOrder set the order of the pseudo http header (case-insensitive).
+// Note this is only valid for http2 and http3.
+// For example:
+//
+//	client.R().SetPseudoHeaderOrder(
+//	    ":scheme",
+//	    ":authority",
+//	    ":path",
+//	    ":method",
+//	).Get(url)
 func (r *Request) SetPseudoHeaderOrder(keys ...string) *Request {
 	if r.Headers == nil {
 		r.Headers = make(http.Header)
@@ -1086,10 +1109,10 @@ func (r *Request) SetRetryCount(count int) *Request {
 // implement your own backoff retry algorithm.
 // For example:
 //
-//		 req.SetRetryInterval(func(resp *req.Response, attempt int) time.Duration {
-//	     sleep := 0.01 * math.Exp2(float64(attempt))
-//	     return time.Duration(math.Min(2, sleep)) * time.Second
-//		 })
+//	req.SetRetryInterval(func(resp *req.Response, attempt int) time.Duration {
+//	    sleep := 0.01 * math.Exp2(float64(attempt))
+//	    return time.Duration(math.Min(2, sleep)) * time.Second
+//	})
 func (r *Request) SetRetryInterval(getRetryIntervalFunc GetRetryIntervalFunc) *Request {
 	r.getRetryOption().GetRetryInterval = getRetryIntervalFunc
 	return r
diff --git a/transport.go b/transport.go
index 6bef585c..f1ee7698 100644
--- a/transport.go
+++ b/transport.go
@@ -210,6 +210,15 @@ func (t *Transport) WrapRoundTrip(wrappers ...HttpRoundTripWrapper) *Transport {
 	return t
 }
 
+// SetHeaderOrder set the order of the http header (case-insensitive).
+// For example:
+//
+//	t.SetHeaderOrder(
+//	    "custom-header",
+//	    "cookie",
+//	    "user-agent",
+//	    "accept-encoding",
+//	)
 func (t *Transport) SetHeaderOrder(keys ...string) {
 	t.WrapRoundTripFunc(func(rt http.RoundTripper) HttpRoundTripFunc {
 		return func(req *http.Request) (resp *http.Response, err error) {
@@ -222,6 +231,16 @@ func (t *Transport) SetHeaderOrder(keys ...string) {
 	})
 }
 
+// SetPseudoHeaderOder set the order of the pseudo http header (case-insensitive).
+// Note this is only valid for http2 and http3.
+// For example:
+//
+//	t.SetPseudoHeaderOrder(
+//	    ":scheme",
+//	    ":authority",
+//	    ":path",
+//	    ":method",
+//	)
 func (t *Transport) SetPseudoHeaderOder(keys ...string) {
 	t.WrapRoundTripFunc(func(rt http.RoundTripper) HttpRoundTripFunc {
 		return func(req *http.Request) (resp *http.Response, err error) {