Update HTTPRequest Class Documentation

Reword the timeout member definition to indicate that example timeout values are suggestions.
Add definition for timeout constant.

Apply suggestions from code review

Co-authored-by: Yuri Sizov <11782833+YuriSizov@users.noreply.github.com>

1 files changed, 4 insertions, 3 deletions

diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml
index 8c9597804b..877dc9df1f 100644
--- a/doc/classes/HTTPRequest.xml
+++ b/doc/classes/HTTPRequest.xml
@@ -26,7 +26,7 @@
 		    # Note: Don't make simultaneous requests using a single HTTPRequest node.
 		    # The snippet below is provided for reference only.
 		    var body = JSON.new().stringify({"name": "Godette"})
-		    error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body)
+		    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
 		    if error != OK:
 		        push_error("An error occurred in the HTTP request.")
 
@@ -61,7 +61,7 @@
 		    {
 		        { "name", "Godette" }
 		    });
-		    error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, body);
+		    error = httpRequest.Request("https://httpbin.org/post", null, HTTPClient.Method.Post, body);
 		    if (error != Error.Ok)
 		    {
 		        GD.PushError("An error occurred in the HTTP request.");
@@ -253,7 +253,7 @@
 			Maximum number of allowed redirects.
 		</member>
 		<member name="timeout" type="float" setter="set_timeout" getter="get_timeout" default="0.0">
-			If set to a value greater than [code]0.0[/code] before the request starts, the HTTP request will time out after [code]timeout[/code] seconds have passed and the request is not [i]completed[/i] yet. For small HTTP requests such as REST API usage, set [member timeout] to a value between [code]10.0[/code] and [code]30.0[/code] to prevent the application from getting stuck if the request fails to get a response in a timely manner. For file downloads, leave this to [code]0.0[/code] to prevent the download from failing if it takes too much time.
+			The duration to wait in seconds before a request times out. If [member timeout] is set to [code]0.0[/code] then the request will never time out. For simple requests, such as communication with a REST API, it is recommended that [member timeout] is set to a value suitable for the server response time (e.g. between [code]1.0[/code] and [code]10.0[/code]). This will help prevent unwanted timeouts caused by variation in server response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads it is suggested the [member timeout] be set to [code]0.0[/code], disabling the timeout functionality. This will help to prevent large transfers from failing due to exceeding the timeout value.
 		</member>
 		<member name="use_threads" type="bool" setter="set_use_threads" getter="is_using_threads" default="false">
 			If [code]true[/code], multithreading is used to improve performance.
@@ -309,6 +309,7 @@
 			Request reached its maximum redirect limit, see [member max_redirects].
 		</constant>
 		<constant name="RESULT_TIMEOUT" value="13" enum="Result">
+			Request failed due to a timeout. If you expect requests to take a long time, try increasing the value of [member timeout] or setting it to [code]0.0[/code] to remove the timeout completely.
 		</constant>
 	</constants>
 </class>