From e9703ee1aaec34a341d710565edb6021af1520ff Mon Sep 17 00:00:00 2001 From: Jordyfel Date: Thu, 6 Feb 2025 22:16:18 +0200 Subject: [PATCH] Improve documentation of some Resource methods --- core/io/resource.cpp | 2 +- core/io/resource.h | 12 ++++++------ doc/classes/Resource.xml | 14 +++++++------- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/core/io/resource.cpp b/core/io/resource.cpp index 886ec6f5e10..d5e33705c6d 100644 --- a/core/io/resource.cpp +++ b/core/io/resource.cpp @@ -504,7 +504,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()) { diff --git a/core/io/resource.h b/core/io/resource.h index ebc82ceebf9..2e4d03a6b87 100644 --- a/core/io/resource.h +++ b/core/io/resource.h @@ -97,12 +97,12 @@ protected: GDVIRTUAL0(_reset_state); 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 &p_resource); virtual void reload_from_file(); @@ -150,9 +150,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; @@ -162,7 +162,7 @@ public: class ResourceCache { friend class Resource; - friend class ResourceLoader; //need the lock + friend class ResourceLoader; // Need the lock. static Mutex lock; static HashMap resources; #ifdef TOOLS_ENABLED diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 0f3a231cb78..3b19f26dea3 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -23,14 +23,14 @@ - 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. - 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. @@ -85,7 +85,7 @@ - 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. @@ -104,13 +104,13 @@ - 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. - 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]. @@ -118,7 +118,7 @@ - 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. @@ -126,7 +126,7 @@ - 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].