Merge pull request #102499 from Jordyfel/resource-docs

Improve documentation of some `Resource` methods

core/io/resource.cpp

@@ -671,7 +671,7 @@ void Resource::set_as_translation_remapped(bool p_remapped) {
 	}
 }
 
-//helps keep IDs same number when loading/saving scenes. -1 clears ID and it Returns -1 when no id stored
+// Helps keep IDs the same when loading/saving scenes. An empty ID clears the entry, and an empty ID is returned when not found.
 void Resource::set_id_for_path(const String &p_path, const String &p_id) {
 #ifdef TOOLS_ENABLED
 	if (p_id.is_empty()) {

core/io/resource.h

@@ -122,12 +122,12 @@ protected:
 	virtual Ref<Resource> _duplicate(const DuplicateParams &p_params) const;
 
 public:
-	static Node *(*_get_local_scene_func)(); //used by editor
-	static void (*_update_configuration_warning)(); //used by editor
+	static Node *(*_get_local_scene_func)(); // Used by the editor.
+	static void (*_update_configuration_warning)(); // Used by the editor.
 
 	void update_configuration_warning();
 	virtual bool editor_can_reload_from_file();
-	virtual void reset_state(); //for resources that use variable amount of properties, either via _validate_property or _get_property_list, this function needs to be implemented to correctly clear state
+	virtual void reset_state(); // For resources that store state in non-exposed properties, such as via _validate_property or _get_property_list, this function must be implemented to clear them.
 	virtual Error copy_from(const Ref<Resource> &p_resource);
 	virtual void reload_from_file();
 
@@ -178,9 +178,9 @@ public:
 
 	void set_as_translation_remapped(bool p_remapped);
 
-	virtual RID get_rid() const; // some resources may offer conversion to RID
+	virtual RID get_rid() const; // Some resources may offer conversion to RID.
 
-	//helps keep IDs same number when loading/saving scenes. -1 clears ID and it Returns -1 when no id stored
+	// Helps keep IDs the same when loading/saving scenes. An empty ID clears the entry, and an empty ID is returned when not found.
 	void set_id_for_path(const String &p_path, const String &p_id);
 	String get_id_for_path(const String &p_path) const;
 
@@ -192,7 +192,7 @@ VARIANT_ENUM_CAST(Resource::DeepDuplicateMode);
 
 class ResourceCache {
 	friend class Resource;
-	friend class ResourceLoader; //need the lock
+	friend class ResourceLoader; // Need the lock.
 	static Mutex lock;
 	static HashMap<String, Resource *> resources;
 #ifdef TOOLS_ENABLED

doc/classes/Resource.xml

@@ -23,14 +23,14 @@
 		<method name="_reset_state" qualifiers="virtual">
 			<return type="void" />
 			<description>
-				For resources that use a variable number of properties, either via [method Object._validate_property] or [method Object._get_property_list], this method should be implemented to correctly clear the resource's state.
+				For resources that store state in non-exported properties, such as via [method Object._validate_property] or [method Object._get_property_list], this method must be implemented to clear them.
 			</description>
 		</method>
 		<method name="_set_path_cache" qualifiers="virtual const">
 			<return type="void" />
 			<param index="0" name="path" type="String" />
 			<description>
-				Sets the resource's path to [param path] without involving the resource cache.
+				Override this method to execute additional logic after [method set_path_cache] is called on this object.
 			</description>
 		</method>
 		<method name="_setup_local_to_scene" qualifiers="virtual">
@@ -94,7 +94,7 @@
 			<return type="String" />
 			<param index="0" name="path" type="String" />
 			<description>
-				Returns the unique identifier for the resource with the given [param path] from the resource cache. If the resource is not loaded and cached, an empty string is returned.
+				From the internal cache for scene-unique IDs, returns the ID of this resource for the scene at [param path]. If there is no entry, an empty string is returned. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending [ResourceFormatLoader] and [ResourceFormatSaver].
 				[b]Note:[/b] This method is only implemented when running in an editor context. At runtime, it returns an empty string.
 			</description>
 		</method>
@@ -113,13 +113,13 @@
 		<method name="is_built_in" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if the resource is built-in (from the engine) or [code]false[/code] if it is user-defined.
+				Returns [code]true[/code] if the resource is saved on disk as a part of another resource's file.
 			</description>
 		</method>
 		<method name="reset_state">
 			<return type="void" />
 			<description>
-				For resources that use a variable number of properties, either via [method Object._validate_property] or [method Object._get_property_list], override [method _reset_state] to correctly clear the resource's state.
+				Makes the resource clear its non-exported properties. See also [method _reset_state]. Useful when implementing a custom resource format by extending [ResourceFormatLoader] and [ResourceFormatSaver].
 			</description>
 		</method>
 		<method name="set_id_for_path">
@@ -127,7 +127,7 @@
 			<param index="0" name="path" type="String" />
 			<param index="1" name="id" type="String" />
 			<description>
-				Sets the unique identifier to [param id] for the resource with the given [param path] in the resource cache. If the unique identifier is empty, the cache entry using [param path] is removed if it exists.
+				In the internal cache for scene-unique IDs, sets the ID of this resource to [param id] for the scene at [param path]. If [param id] is empty, the cache entry for [param path] is cleared. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending [ResourceFormatLoader] and [ResourceFormatSaver].
 				[b]Note:[/b] This method is only implemented when running in an editor context.
 			</description>
 		</method>
@@ -135,7 +135,7 @@
 			<return type="void" />
 			<param index="0" name="path" type="String" />
 			<description>
-				Sets the resource's path to [param path] without involving the resource cache.
+				Sets the resource's path to [param path] without involving the resource cache. Useful for handling [enum ResourceFormatLoader.CacheMode] values when implementing a custom resource format by extending [ResourceFormatLoader] and [ResourceFormatSaver].
 			</description>
 		</method>
 		<method name="setup_local_to_scene" deprecated="This method should only be called internally.">