Improve the preload and load descriptions

1 files changed, 8 insertions, 8 deletions

diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml
index be159b6407..f04cb4b4c3 100644
--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml
@@ -619,11 +619,11 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
-				Loads a resource from the filesystem located at [code]path[/code].
-				[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing [b]Copy Path[/b].
+				Loads a resource from the filesystem located at [code]path[/code]. The resource is loaded on the method call (unless it's referenced already elsewhere, e.g. in another script or in the scene), which might cause slight delay, especially when loading scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use [method preload].
+				[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
 				[codeblock]
-				# Load a scene called main located in the root of the project directory.
-				var main = load("res://main.tscn")
+				# Load a scene called main located in the root of the project directory and cache it in a variable.
+				var main = load("res://main.tscn") # main will contain a PackedScene resource.
 				[/codeblock]
 				[b]Important:[/b] The path must be absolute, a local path will just return [code]null[/code].
 			</description>
@@ -797,11 +797,11 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
-				Returns a resource from the filesystem that is loaded during script parsing.
-				[b]Note:[/b] Resource paths can be obtained by right clicking on a resource in the Assets Panel and choosing "Copy Path".
+				Returns a [Resource] from the filesystem located at [code]path[/code]. The resource is loaded during script parsing, i.e. is loaded with the script and [method preload] effectively acts as a reference to that resource. Note that the method requires a constant path. If you want to load a resource from a dynamic/variable path, use [method load].
+				[b]Note:[/b] Resource paths can be obtained by right clicking on a resource in the Assets Panel and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
 				[codeblock]
-				# Load a scene called main located in the root of the project directory.
-				var main = preload("res://main.tscn")
+				# Instance a scene.
+				var diamond = preload("res://diamond.tscn").instance()
 				[/codeblock]
 			</description>
 		</method>