doc: Improve docs for Resource* classes

Also move module-specific classes to their own module's `doc_classes`
folder.

(cherry picked from commit 0764451dc5)

doc/classes/File.xml

@@ -115,7 +115,7 @@
 			<return type="int" enum="Error">
 			</return>
 			<description>
-				Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [@GlobalScope].
+				Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [enum @GlobalScope.Error].
 			</description>
 		</method>
 		<method name="get_float" qualifiers="const">
@@ -241,7 +241,7 @@
 			<argument index="2" name="compression_mode" type="int" default="0">
 			</argument>
 			<description>
-				Opens a compressed file for reading or writing. Use COMPRESSION_* constants to set [code]compression_mode[/code].
+				Opens a compressed file for reading or writing. Use [enum CompressionMode] constants to set [code]compression_mode[/code].
 			</description>
 		</method>
 		<method name="open_encrypted">

doc/classes/Resource.xml

@@ -4,7 +4,7 @@
 		Base class for all resources.
 	</brief_description>
 	<description>
-		Resource is the base class for all resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also loaded only once from disk, and further attempts to load the resource will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource.
+		Resource is the base class for all Godot-specific resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource.
 	</description>
 	<tutorials>
 		<link>https://docs.godotengine.org/en/3.1/getting_started/step_by_step/resources.html</link>
@@ -14,6 +14,7 @@
 			<return type="void">
 			</return>
 			<description>
+				Virtual function which can be overridden to customize the behavior value of [method setup_local_to_scene].
 			</description>
 		</method>
 		<method name="duplicate" qualifiers="const">
@@ -29,6 +30,7 @@
 			<return type="Node">
 			</return>
 			<description>
+				If [member resource_local_to_scene] is enabled and the resource was loaded from a [PackedScene] instantiation, returns the local scene where this resource's unique copy is in use. Otherwise, returns [code]null[/code].
 			</description>
 		</method>
 		<method name="get_rid" qualifiers="const">
@@ -42,6 +44,8 @@
 			<return type="void">
 			</return>
 			<description>
+				This method is called when a resource with [member resource_local_to_scene] enabled is loaded from a [PackedScene] instantiation. Its behavior can be customized by overriding [method _setup_local_to_scene] from script.
+				For most resources, this method performs no base logic. [ViewportTexture] performs custom logic to properly set the proxy texture and flags in the local viewport.
 			</description>
 		</method>
 		<method name="take_over_path">
@@ -50,12 +54,13 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
-				Sets the path of the resource. Differs from [code]set_path()[/code], if another [code]Resource[/code] exists with "path" it over-takes it, instead of failing.
+				Sets the path of the resource, potentially overriding an existing cache entry for this path. This differs from setting [member resource_path], as the latter would error out if another resource was already cached for the given path.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene">
+			If [code]true[/code], the resource will be made unique in each instance of its local scene. It can thus be modified in a scene instance without impacting other instances of that same scene.
 		</member>
 		<member name="resource_name" type="String" setter="set_name" getter="get_name">
 			The name of the resource. This is an optional identifier.

doc/classes/ResourceFormatLoader.xml

@@ -4,9 +4,9 @@
 		Loads a specific resource type from a file.
 	</brief_description>
 	<description>
-		Godot loads resources in the editor or in exported games using ResourceFormatLoaders. They get queried when you call [code]load[/code], or when a resource with internal dependencies is loaded. Each file type may load as a different resource type, so multiple ResourceFormatLoader are registered in the engine.
+		Godot loads resources in the editor or in exported games using ResourceFormatLoaders. They are queried automatically via the [ResourceLoader] singleton, or when a resource with internal dependencies is loaded. Each file type may load as a different resource type, so multiple ResourceFormatLoaders are registered in the engine.
-		Extending this class allows you to define your own. You should give it a global class name with [code]class_name[/code] for it to be registered. You may as well implement a [ResourceFormatSaver].
+		Extending this class allows you to define your own loader. Be sure to respect the documented return types and values. You should give it a global class name with [code]class_name[/code] for it to be registered. Like built-in ResourceFormatLoaders, it will be called automatically when loading resources of its handled type(s). You may also implement a [ResourceFormatSaver].
-		Note: You can also extend [EditorImportPlugin] if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends if the format is suitable or not for the final exported game. Example: it's better to import .PNG textures as .STEX first, so they can be loaded with better efficiency on the graphics card.
+		Note: You can also extend [EditorImportPlugin] if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends if the format is suitable or not for the final exported game. For example, it's better to import [code].png[/code] textures as [code].stex[/code] ([StreamTexture]) first, so they can be loaded with better efficiency on the graphics card.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -19,7 +19,7 @@
 			<argument index="1" name="add_types" type="String">
 			</argument>
 			<description>
-				If implemented, gets the dependencies of a given resource. If [code]add_types[/code] is [code]true[/code], paths should be appended [code]::TypeName[/code], where [code]TypeName[/code] is the class name of the dependency. Note that custom resource types defined by scripts aren't known by the [ClassDB], so you might just return [code]Resource[/code] for them.
+				If implemented, gets the dependencies of a given resource. If [code]add_types[/code] is [code]true[/code], paths should be appended [code]::TypeName[/code], where [code]TypeName[/code] is the class name of the dependency. Note that custom resource types defined by scripts aren't known by the [ClassDB], so you might just return [code]"Resource"[/code] for them.
 			</description>
 		</method>
 		<method name="get_recognized_extensions" qualifiers="virtual">
@@ -55,7 +55,7 @@
 			<argument index="1" name="original_path" type="String">
 			</argument>
 			<description>
-				Loads a resource when the engine finds this loader to be compatible. If the loaded resource is the result of an import, [code]original_path[/code] will target the source file. Returns a resource object if succeeded, or an [code]ERR_*[/code] constant listed in [@GlobalScope] if it failed.
+				Loads a resource when the engine finds this loader to be compatible. If the loaded resource is the result of an import, [code]original_path[/code] will target the source file. Returns a [Resource] object on success, or an [enum @GlobalScope.Error] constant in case of failure.
 			</description>
 		</method>
 		<method name="rename_dependencies" qualifiers="virtual">
@@ -66,7 +66,8 @@
 			<argument index="1" name="renames" type="String">
 			</argument>
 			<description>
-				If implemented, renames dependencies within the given resource and saves it. [code]renames[/code] is a dictionary [code]{ String =&gt; String }[/code] mapping old dependency paths to new paths. Returns [code]OK[/code] on success, or an [code]ERR_*[/code] constant listed in [@GlobalScope] in case of failure.
+				If implemented, renames dependencies within the given resource and saves it. [code]renames[/code] is a dictionary [code]{ String =&gt; String }[/code] mapping old dependency paths to new paths.
+				Returns [constant @GlobalScope.OK] on success, or an [enum @GlobalScope.Error] constant in case of failure.
 			</description>
 		</method>
 	</methods>

doc/classes/ResourceFormatSaver.xml

@@ -4,8 +4,8 @@
 		Saves a specific resource type to a file.
 	</brief_description>
 	<description>
-		The engine can save resources when you do it from the editor, or when you call [method ResourceSaver.save]. This is accomplished with multiple [code]ResourceFormatSaver[/code]s, each handling its own format.
+		The engine can save resources when you do it from the editor, or when you use the [ResourceSaver] singleton. This is accomplished thanks to multiple [ResourceFormatSaver]s, each handling its own format and called automatically by the engine.
-		By default, Godot saves resources as [code].tres[/code], [code].res[/code] or another built-in format, but you can choose to create your own format by extending this class. You should give it a global class name with [code]class_name[/code] for it to be registered. You may as well implement a [ResourceFormatLoader].
+		By default, Godot saves resources as [code].tres[/code] (text-based), [code].res[/code] (binary) or another built-in format, but you can choose to create your own format by extending this class. Be sure to respect the documented return types and values. You should give it a global class name with [code]class_name[/code] for it to be registered. Like built-in ResourceFormatSavers, it will be called automatically when saving resources of its recognized type(s). You may also implement a [ResourceFormatLoader].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -16,7 +16,7 @@
 			<argument index="0" name="resource" type="Resource">
 			</argument>
 			<description>
-				Gets the list of extensions for files this saver is able to write.
+				Returns the list of extensions available for saving the resource object, provided it is recognized (see [method recognize]).
 			</description>
 		</method>
 		<method name="recognize" qualifiers="virtual">
@@ -25,7 +25,7 @@
 			<argument index="0" name="resource" type="Resource">
 			</argument>
 			<description>
-				Returns [code]true[/code] if the given resource object can be saved by this saver.
+				Returns whether the given resource object can be saved by this saver.
 			</description>
 		</method>
 		<method name="save" qualifiers="virtual">
@@ -38,7 +38,8 @@
 			<argument index="2" name="flags" type="int">
 			</argument>
 			<description>
-				Saves the given resource object to a file. [code]flags[/code] is a bitmask composed with [code]FLAG_*[/code] constants defined in [ResourceSaver]. Returns [code]OK[/code] on success, or an [code]ERR_*[/code] constant listed in [@GlobalScope] if it failed.
+				Saves the given resource object to a file at the target [code]path[/code]. [code]flags[/code] is a bitmask composed with [enum ResourceSaver.SaverFlags] constants.
+				Returns [constant @GlobalScope.OK] on success, or an [enum @GlobalScope.Error] constant in case of failure.
 			</description>
 		</method>
 	</methods>

doc/classes/ResourceInteractiveLoader.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="ResourceInteractiveLoader" inherits="Reference" category="Core" version="3.1.2">
 	<brief_description>
-		Interactive Resource Loader.
+		Interactive [Resource] loader.
 	</brief_description>
 	<description>
-		Interactive Resource Loader. This object is returned by ResourceLoader when performing an interactive load. It allows to load with high granularity, so this is mainly useful for displaying load bars/percentages.
+		Interactive [Resource] loader. This object is returned by [ResourceLoader] when performing an interactive load. It allows to load with high granularity, so this is mainly useful for displaying loading bars/percentages.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,14 +13,14 @@
 			<return type="Resource">
 			</return>
 			<description>
-				Returns the loaded resource (only if loaded). Otherwise, returns null.
+				Returns the loaded resource if the load operation completed successfully, [code]null[/code] otherwise.
 			</description>
 		</method>
 		<method name="get_stage" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Returns the load stage. The total amount of stages can be queried with [method get_stage_count]
+				Returns the load stage. The total amount of stages can be queried with [method get_stage_count].
 			</description>
 		</method>
 		<method name="get_stage_count" qualifiers="const">
@@ -34,13 +34,19 @@
 			<return type="int" enum="Error">
 			</return>
 			<description>
-				Poll the load. If OK is returned, this means poll will have to be called again. If ERR_FILE_EOF is returned, them the load has finished and the resource can be obtained by calling [method get_resource].
+				Polls the loading operation, i.e. loads a data chunk up to the next stage.
+				Returns [constant @GlobalScope.OK] if the poll is successful but the load operation has not finished yet (intermediate stage). This means [method poll] will have to be called again until the last stage is completed.
+				Returns [constant @GlobalScope.ERR_FILE_EOF] if the load operation has completed successfully. The loaded resource can be obtained by calling [method get_resource].
+				Returns another [enum @GlobalScope.Error] code if the poll has failed.
 			</description>
 		</method>
 		<method name="wait">
 			<return type="int" enum="Error">
 			</return>
 			<description>
+				Polls the loading operation successively until the resource is completely loaded or a [method poll] fails.
+				Returns [constant @GlobalScope.ERR_FILE_EOF] if the load operation has completed successfully. The loaded resource can be obtained by calling [method get_resource].
+				Returns another [enum @GlobalScope.Error] code if a poll has failed, aborting the operation.
 			</description>
 		</method>
 	</methods>

doc/classes/ResourceLoader.xml

@@ -1,10 +1,12 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="ResourceLoader" inherits="Object" category="Core" version="3.1.2">
 	<brief_description>
-		Resource Loader.
+		Singleton used to load resource files.
 	</brief_description>
 	<description>
-		Resource Loader. This is a static object accessible as [code]ResourceLoader[/code]. GDScript has a simplified load() function, though.
+		Singleton used to load resource files from the filesystem.
+		It uses the many [ResourceFormatLoader] classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine.
+		GDScript has a simplified [method @GDScript.load] built-in method which can be used in most situations, leaving the use of [ResourceLoader] for more advanced scenarios.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -17,6 +19,8 @@
 			<argument index="1" name="type_hint" type="String" default="&quot;&quot;">
 			</argument>
 			<description>
+				Returns whether a recognized resource exists for the given [code]path[/code].
+				An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader].
 			</description>
 		</method>
 		<method name="get_dependencies">
@@ -25,6 +29,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Returns the dependencies for the resource at the given [code]path[/code].
 			</description>
 		</method>
 		<method name="get_recognized_extensions_for_type">
@@ -42,6 +47,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Deprecated method. Use [method has_cached] or [method exists] instead.
 			</description>
 		</method>
 		<method name="has_cached">
@@ -50,6 +56,8 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Returns whether a cached resource is available for the given [code]path[/code].
+				Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the [method load] or [method load_interactive] methods will use the cached version. The cached resource can be overridden by using [method Resource.take_over_path] on a new resource for that same path.
 			</description>
 		</method>
 		<method name="load">
@@ -62,6 +70,11 @@
 			<argument index="2" name="no_cache" type="bool" default="false">
 			</argument>
 			<description>
+				Loads a resource at the given [code]path[/code], caching the result for further access.
+				The registered [ResourceFormatLoader]s are queried sequentially to find the first one which can handle the file's extension, and then attempt loading. If loading fails, the remaining ResourceFormatLoaders are also attempted.
+				An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader].
+				If [code]no_cache[/code] is [code]true[/code], the resource cache will be bypassed and the resource will be loaded anew. Otherwise, the cached resource will be returned if it exists.
+				Returns an empty resource if no ResourceFormatLoader could handle the file.
 			</description>
 		</method>
 		<method name="load_interactive">
@@ -72,7 +85,8 @@
 			<argument index="1" name="type_hint" type="String" default="&quot;&quot;">
 			</argument>
 			<description>
-				Load a resource interactively, the returned object allows to load with high granularity.
+				Starts loading a resource interactively. The returned [ResourceInteractiveLoader] object allows to load with high granularity, calling its [method ResourceInteractiveLoader.poll] method successively to load chunks.
+				An optional [code]type_hint[/code] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader].
 			</description>
 		</method>
 		<method name="set_abort_on_missing_resources">

doc/classes/ResourcePreloader.xml

@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		This node is used to preload sub-resources inside a scene, so when the scene is loaded, all the resources are ready to use and can be retrieved from the preloader.
+		GDScript has a simplified [method @GDScript.preload] built-in method which can be used in most situations, leaving the use of [ResourcePreloader] for more advanced scenarios.
 	</description>
 	<tutorials>
 	</tutorials>

doc/classes/ResourceSaver.xml

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="ResourceSaver" inherits="Object" category="Core" version="3.1.2">
 	<brief_description>
-		Resource saving interface.
+		Singleton for saving Godot-specific resource types.
 	</brief_description>
 	<description>
-		Resource saving interface, used for saving resources to disk.
+		Singleton for saving Godot-specific resource types to the filesystem.
+		It uses the many [ResourceFormatSaver] classes registered in the engine (either built-in or from a plugin) to save engine-specific resource data to text-based (e.g. [code].tres[/code] or [code].tscn[/code]) or binary files (e.g. [code].res[/code] or [code].scn[/code]).
 	</description>
 	<tutorials>
 	</tutorials>
@@ -28,24 +29,33 @@
 			<argument index="2" name="flags" type="int" default="0">
 			</argument>
 			<description>
-				Saves a resource to disk.
+				Saves a resource to disk to the given path, using a [ResourceFormatSaver] that recognizes the resource object.
+				The [code]flags[/code] bitmask can be specified to customize the save behavior.
+				Returns [constant @GlobalScope.OK] on success.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="FLAG_RELATIVE_PATHS" value="1" enum="SaverFlags">
+			Save the resource with a path relative to the scene which uses it.
 		</constant>
 		<constant name="FLAG_BUNDLE_RESOURCES" value="2" enum="SaverFlags">
+			Bundles external resources.
 		</constant>
 		<constant name="FLAG_CHANGE_PATH" value="4" enum="SaverFlags">
+			Change the [member Resource.resource_path] of the saved resource to match its new location.
 		</constant>
 		<constant name="FLAG_OMIT_EDITOR_PROPERTIES" value="8" enum="SaverFlags">
+			Do not save editor-specific metadata (identified by their [code]__editor[/code] prefix).
 		</constant>
 		<constant name="FLAG_SAVE_BIG_ENDIAN" value="16" enum="SaverFlags">
+			Save as big endian (see [member File.endian_swap]).
 		</constant>
 		<constant name="FLAG_COMPRESS" value="32" enum="SaverFlags">
+			Compress the resource on save using [constant File.COMPRESSION_ZSTD]. Only available for binary resource types.
 		</constant>
 		<constant name="FLAG_REPLACE_SUBRESOURCE_PATHS" value="64" enum="SaverFlags">
+			Take over the paths of the saved subresources (see [method Resource.take_over_path]).
 		</constant>
 	</constants>
 </class>

modules/gdnative/config.py

@@ -6,6 +6,7 @@ def configure(env):
 
 def get_doc_classes():
     return [
+        "@NativeScript",
         "ARVRInterfaceGDNative",
         "GDNative",
         "GDNativeLibrary",

modules/gdscript/config.py

@@ -6,6 +6,7 @@ def configure(env):
 
 def get_doc_classes():
     return [
+        "@GDScript",
         "GDScript",
         "GDScriptFunctionState",
         "GDScriptNativeClass",

modules/visual_script/config.py

@@ -6,6 +6,7 @@ def configure(env):
 
 def get_doc_classes():
     return [
+        "@VisualScript",
         "VisualScriptBasicTypeConstant",
         "VisualScriptBuiltinFunc",
         "VisualScriptClassConstant",