update client use documentation

client.go

@@ -100,6 +100,11 @@ func (c *Client) Head() *Request {
 }
 
 // Method defines a the default HTTP method used by outgoing client requests.
+//
+// ⚠️ Method employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.Method()` instead.
 func (c *Client) Method(name string) *Client {
 	c.Middleware.UseRequest(func(ctx *context.Context, h context.Handler) {
 		ctx.Request.Method = name
@@ -110,77 +115,137 @@ func (c *Client) Method(name string) *Client {
 
 // URL defines the URL for client requests.
 // Useful to define at client level the base URL and base path used by child requests.
+//
+// ⚠️ URL employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.URL()` instead.
 func (c *Client) URL(uri string) *Client {
 	c.Use(url.URL(uri))
 	return c
 }
 
 // BaseURL defines the URL schema and host for client requests.
 // Useful to define at client level the base URL used by client child requests.
+//
+// ⚠️ BaseURL employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.BaseURL()` instead.
 func (c *Client) BaseURL(uri string) *Client {
 	c.Use(url.BaseURL(uri))
 	return c
 }
 
 // Path defines the URL base path for client requests.
+//
+// ⚠️ Path employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.Path()` instead.
 func (c *Client) Path(path string) *Client {
 	c.Use(url.Path(path))
 	return c
 }
 
 // AddPath concatenates a path slice to the existent path in at client level.
+//
+// ⚠️ AddPath employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.AddPath()` instead.
 func (c *Client) AddPath(path string) *Client {
 	c.Use(url.AddPath(path))
 	return c
 }
 
 // Param replaces a path param based on the given param name and value.
+//
+// ⚠️ Param employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.Param()` instead.
 func (c *Client) Param(name, value string) *Client {
 	c.Use(url.Param(name, value))
 	return c
 }
 
 // Params replaces path params based on the given params key-value map.
+//
+// ⚠️ Params employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.Params()` instead.
 func (c *Client) Params(params map[string]string) *Client {
 	c.Use(url.Params(params))
 	return c
 }
 
 // SetHeader sets a new header field by name and value.
 // If another header exists with the same key, it will be overwritten.
+//
+// ⚠️ SetHeader employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.SetHeader()` instead.
 func (c *Client) SetHeader(key, value string) *Client {
 	c.Use(headers.Set(key, value))
 	return c
 }
 
 // AddHeader adds a new header field by name and value
 // without overwriting any existent header.
+//
+// ⚠️ AddHeader employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.AddHeader()` instead.
 func (c *Client) AddHeader(name, value string) *Client {
 	c.Use(headers.Add(name, value))
 	return c
 }
 
 // SetHeaders adds new header fields based on the given map.
+//
+// ⚠️ SetHeaders employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.SetHeaders()` instead.
 func (c *Client) SetHeaders(fields map[string]string) *Client {
 	c.Use(headers.SetMap(fields))
 	return c
 }
 
 // AddCookie sets a new cookie field based on the given http.Cookie struct
 // without overwriting any existent cookie.
+//
+// ⚠️ AddCookie employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.AddCookie()` instead.
 func (c *Client) AddCookie(cookie *http.Cookie) *Client {
 	c.Use(cookies.Add(cookie))
 	return c
 }
 
 // AddCookies sets a new cookie field based on a list of http.Cookie
 // without overwriting any existent cookie.
+//
+// ⚠️ AddCookies employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.AddCookies()` instead.
 func (c *Client) AddCookies(data []*http.Cookie) *Client {
 	c.Use(cookies.AddMultiple(data))
 	return c
 }
 
 // CookieJar creates a cookie jar to store HTTP cookies when they are sent down.
+//
+// ⚠️ CookieJar employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.CookieJar()` instead.
 func (c *Client) CookieJar() *Client {
 	c.Use(cookies.Jar())
 	return c
@@ -198,30 +263,60 @@ func (c *Client) UseContext(cancelContext gocontext.Context) *Client {
 }
 
 // Use uses a new plugin to the middleware stack.
+//
+// ⚠️ Use employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+//
+// Use `Request.Use()` instead.
+//
+// Example:
+// httpClient.Use(middleware).Post() // Middleware applies to ALL requests (⚠️ use with caution!)
+// httpClient.Post().Use(middleware) // Middleware applies ONLY to this request (✅ recommended)
 func (c *Client) Use(p plugin.Plugin) *Client {
 	c.Middleware.Use(p)
 	return c
 }
 
 // UseRequest uses a new middleware function for request phase.
+//
+// ⚠️ UseRequest employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.UseRequest()` instead.
 func (c *Client) UseRequest(fn context.HandlerFunc) *Client {
 	c.Middleware.UseRequest(fn)
 	return c
 }
 
 // UseResponse uses a new middleware function for response phase.
+//
+// ⚠️ UseResponse employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.UseResponse()` instead.
 func (c *Client) UseResponse(fn context.HandlerFunc) *Client {
 	c.Middleware.UseResponse(fn)
 	return c
 }
 
 // UseError uses a new middleware function for error phase.
+//
+// ⚠️ UseError employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.UseError()` instead.
 func (c *Client) UseError(fn context.HandlerFunc) *Client {
 	c.Middleware.UseError(fn)
 	return c
 }
 
 // UseHandler uses a new middleware function for the given phase.
+//
+// ⚠️ UseHandler employs a new plugin within the middleware stack.
+// Exercise caution when utilising this method. Considering its applicability to all requests, it may yield unforeseen consequences.
+// Behaviours, such as mutex locks, may lead to complications if misused. Should you require middleware for a single request only?
+// use `Request.UseHandler()` instead.
 func (c *Client) UseHandler(phase string, fn context.HandlerFunc) *Client {
 	c.Middleware.UseHandler(phase, fn)
 	return c