From 544f65a522d8a001e2effe49a81d8c00ef5e1685 Mon Sep 17 00:00:00 2001
From: Relintai <relintai@relintai.net>
Date: Sun, 11 May 2025 22:40:26 +0200
Subject: [PATCH] Docs for the UserManager implementations.

---
 modules/users/doc_classes/UserManagerDB.xml   | 45 +++++++++++++++++++
 modules/users/doc_classes/UserManagerFile.xml |  4 ++
 .../users/doc_classes/UserManagerStatic.xml   |  9 ++++
 3 files changed, 58 insertions(+)

diff --git a/modules/users/doc_classes/UserManagerDB.xml b/modules/users/doc_classes/UserManagerDB.xml
index 8f8f6a55c..722cb56b6 100644
--- a/modules/users/doc_classes/UserManagerDB.xml
+++ b/modules/users/doc_classes/UserManagerDB.xml
@@ -1,8 +1,30 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="UserManagerDB" inherits="UserManager">
 	<brief_description>
+		A UserManager implementation that uses databases to store [User]s.
 	</brief_description>
 	<description>
+		A UserManager implementation that uses databases to store [User]s.
+		Either uses the [Database] set to it's [code]database[/code] property, or it uses the default database.
+		Uses the database module, so it's only available if it's enabled during compile time.
+		The current default database cration code:
+		[code]var tb : TableBuilder = get_table_builder()
+		tb.create_table(_database_table_name)
+		tb.integer("id").auto_increment().next_row()
+		tb.varchar("username", 60).not_null().next_row()
+		tb.varchar("username_internal", 60).not_null().next_row()
+		tb.varchar("email", 100).not_null().next_row()
+		tb.varchar("email_internal", 100).not_null().next_row()
+		tb.integer("rank").not_null().next_row()
+		tb.varchar("pre_salt", 100).next_row()
+		tb.varchar("post_salt", 100).next_row()
+		tb.varchar("password_hash", 100).next_row()
+		tb.integer("banned").next_row()
+		tb.varchar("password_reset_token", 100).next_row()
+		tb.integer("locked").next_row()
+		tb.primary_key("id")
+		tb.ccreate_table()
+		tb.run_query()[/code]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,16 +33,20 @@
 			<return type="void" />
 			<argument index="0" name="pseed" type="int" />
 			<description>
+				Override this method to create default user entries when the database gets seeded.
+				By default this does not create anything.
 			</description>
 		</method>
 		<method name="_create_table" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Create the required table(s).
 			</description>
 		</method>
 		<method name="_drop_table" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Drop the required table(s).
 			</description>
 		</method>
 		<method name="_migrate" qualifiers="virtual">
@@ -29,43 +55,55 @@
 			<argument index="1" name="should_seed" type="bool" />
 			<argument index="2" name="pseed" type="int" />
 			<description>
+				Standard migration method called by the database singleton.
 			</description>
 		</method>
 		<method name="_update_table" qualifiers="virtual">
 			<return type="void" />
 			<argument index="0" name="current_table_version" type="int" />
 			<description>
+				Update your tables if necessary.
+				[method _migrate] calls this when needed.
 			</description>
 		</method>
 		<method name="create_default_entries">
 			<return type="void" />
 			<argument index="0" name="pseed" type="int" />
 			<description>
+				[method _migrate] calls this when needed.
+				Calls [method _create_default_entries].
 			</description>
 		</method>
 		<method name="create_table">
 			<return type="void" />
 			<description>
+				Creates the required table(s).
+				Calls [method _create_table].
 			</description>
 		</method>
 		<method name="drop_table">
 			<return type="void" />
 			<description>
+				Drop the required table(s).
+				Calls [method _drop_table].
 			</description>
 		</method>
 		<method name="get_database_connection">
 			<return type="DatabaseConnection" />
 			<description>
+				Get a [DatabaseConnection] from the current database.
 			</description>
 		</method>
 		<method name="get_query_builder">
 			<return type="QueryBuilder" />
 			<description>
+				Get a [QueryBuilder] from the current database.
 			</description>
 		</method>
 		<method name="get_table_builder">
 			<return type="TableBuilder" />
 			<description>
+				Get a [TableBuilder] from the current database.
 			</description>
 		</method>
 		<method name="migrate">
@@ -74,19 +112,26 @@
 			<argument index="1" name="pseed" type="bool" />
 			<argument index="2" name="arg2" type="int" />
 			<description>
+				Standard migration method called by the database singleton.
+				Calls [method _migrate].
 			</description>
 		</method>
 		<method name="update_table">
 			<return type="void" />
 			<argument index="0" name="current_table_version" type="int" />
 			<description>
+				Update your tables if necessary.
+				[method _migrate] calls this when needed.
+				Calls [method _update_table].
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="database" type="Database" setter="set_database" getter="get_database">
+			Lets you set a custom [Database] to be used if [DatabaseManager.ddb] isn't desired.
 		</member>
 		<member name="database_table_name" type="String" setter="set_database_table_name" getter="get_database_table_name" default="&quot;users&quot;">
+			Lets you specify a table name.
 		</member>
 	</members>
 	<constants>
diff --git a/modules/users/doc_classes/UserManagerFile.xml b/modules/users/doc_classes/UserManagerFile.xml
index 5113d93ae..a758d4ef1 100644
--- a/modules/users/doc_classes/UserManagerFile.xml
+++ b/modules/users/doc_classes/UserManagerFile.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="UserManagerFile" inherits="UserManager">
 	<brief_description>
+		A UserManager implementation that uses file to store [User]s.
 	</brief_description>
 	<description>
+		A UserManager implementation that uses file to store [User]s.
+		Uses one file per user, and stores data in the json format, so An exclusive folder is recommended that is not used by anything else.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,6 +13,7 @@
 	</methods>
 	<members>
 		<member name="save_folder_path" type="String" setter="set_save_folder_path" getter="get_save_folder_path" default="&quot;user://users/&quot;">
+			The folder where the user data will be stored.
 		</member>
 	</members>
 	<constants>
diff --git a/modules/users/doc_classes/UserManagerStatic.xml b/modules/users/doc_classes/UserManagerStatic.xml
index 81c459a2d..af257edc5 100644
--- a/modules/users/doc_classes/UserManagerStatic.xml
+++ b/modules/users/doc_classes/UserManagerStatic.xml
@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="UserManagerStatic" inherits="UserManager">
 	<brief_description>
+		A UserManager implementation that stores users using it's properties inside the tree.
 	</brief_description>
 	<description>
+		A UserManager implementation that stores users using it's properties inside the tree.
+		Users can be created inside the editor using the inspector.
+		Can be used for testing, and maybe for small non-public facing applications.
+		It's data is serialized with the scene, so it will get restored on restart.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,12 +15,16 @@
 	</methods>
 	<members>
 		<member name="create_user_email" type="String" setter="set_create_user_email" getter="get_create_user_email" default="&quot;&quot;">
+			Used by the editor.
 		</member>
 		<member name="create_user_name" type="String" setter="set_create_user_name" getter="get_create_user_name" default="&quot;&quot;">
+			Used by the editor.
 		</member>
 		<member name="create_user_password" type="String" setter="set_create_user_password" getter="get_create_user_password" default="&quot;&quot;">
+			Used by the editor.
 		</member>
 		<member name="users" type="Array" setter="set_users" getter="get_users" default="[  ]">
+			The list of stored [User]s.
 		</member>
 	</members>
 	<constants>