From ae2ebfbc4936af8a607c92550fbb417c7536c244 Mon Sep 17 00:00:00 2001
From: RedMser <redmser.jj2@gmail.com>
Date: Wed, 3 Aug 2022 19:59:11 +0200
Subject: [PATCH] Add ResourceUID documentation

---
 doc/classes/@GlobalScope.xml |  1 +
 doc/classes/ResourceUID.xml  | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 709863b70f6..d6476213622 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -1209,6 +1209,7 @@
 			The [ResourceSaver] singleton.
 		</member>
 		<member name="ResourceUID" type="ResourceUID" setter="" getter="">
+			The [ResourceUID] singleton.
 		</member>
 		<member name="TextServerManager" type="TextServerManager" setter="" getter="">
 			The [TextServerManager] singleton.
diff --git a/doc/classes/ResourceUID.xml b/doc/classes/ResourceUID.xml
index f91c39b512e..782a8a29687 100644
--- a/doc/classes/ResourceUID.xml
+++ b/doc/classes/ResourceUID.xml
@@ -1,8 +1,12 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="ResourceUID" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Singleton for managing a cache of resource UIDs within a project.
 	</brief_description>
 	<description>
+		Resources can not only be referenced using their resource paths [code]res://[/code], but alternatively through a unique identifier specified via [code]uid://[/code].
+		Using UIDs allows for the engine to keep references between resources intact, even if the files get renamed or moved.
+		This singleton is responsible for keeping track of all registered resource UIDs of a project, generating new UIDs and converting between the string and integer representation.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -12,35 +16,45 @@
 			<argument index="0" name="id" type="int" />
 			<argument index="1" name="path" type="String" />
 			<description>
+				Adds a new UID value which is mapped to the given resource path.
+				Fails with an error if the UID already exists, so be sure to check [method has_id] beforehand, or use [method set_id] instead.
 			</description>
 		</method>
 		<method name="create_id">
 			<return type="int" />
 			<description>
+				Generates a random resource UID which is guaranteed to be unique within the list of currently loaded UIDs.
+				In order for this UID to be registered, you must call [method add_id] or [method set_id].
 			</description>
 		</method>
 		<method name="get_id_path" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="id" type="int" />
 			<description>
+				Returns the path that the given UID value refers to.
+				Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand.
 			</description>
 		</method>
 		<method name="has_id" qualifiers="const">
 			<return type="bool" />
 			<argument index="0" name="id" type="int" />
 			<description>
+				Returns whether the given UID value is known to the cache.
 			</description>
 		</method>
 		<method name="id_to_text" qualifiers="const">
 			<return type="String" />
 			<argument index="0" name="id" type="int" />
 			<description>
+				Converts the given UID to a [code]uid://[/code] string value.
 			</description>
 		</method>
 		<method name="remove_id">
 			<return type="void" />
 			<argument index="0" name="id" type="int" />
 			<description>
+				Removes a loaded UID value from the cache.
+				Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand.
 			</description>
 		</method>
 		<method name="set_id">
@@ -48,17 +62,22 @@
 			<argument index="0" name="id" type="int" />
 			<argument index="1" name="path" type="String" />
 			<description>
+				Updates the resource path of an existing UID.
+				Fails with an error if the UID does not exist, so be sure to check [method has_id] beforehand, or use [method add_id] instead.
 			</description>
 		</method>
 		<method name="text_to_id" qualifiers="const">
 			<return type="int" />
 			<argument index="0" name="text_id" type="String" />
 			<description>
+				Extracts the UID value from the given [code]uid://[/code] string.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="INVALID_ID" value="-1">
+			The value to use for an invalid UID, for example if the resource could not be loaded.
+			Its text representation is [code]uid://&lt;invalid&gt;[/code].
 		</constant>
 	</constants>
 </class>