From 0c463a87213c3312d34b9f75085a9bb0af79e75c Mon Sep 17 00:00:00 2001
From: "Dylan K. Taylor" <dktapps@pmmp.io>
Date: Tue, 15 Nov 2022 21:45:08 +0000
Subject: [PATCH] PlayerCreationEvent: update woefully inadequate documentation

closes #4581
---
 src/event/player/PlayerCreationEvent.php | 26 +++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/event/player/PlayerCreationEvent.php b/src/event/player/PlayerCreationEvent.php
index 7e7e2cfaa..64f449d1a 100644
--- a/src/event/player/PlayerCreationEvent.php
+++ b/src/event/player/PlayerCreationEvent.php
@@ -30,7 +30,20 @@ use pocketmine\utils\Utils;
 use function is_a;
 
 /**
- * Allows the creation of players overriding the base Player class
+ * Allows the use of custom Player classes. This enables overriding built-in Player methods to change behaviour that is
+ * not possible to alter any other way.
+ *
+ * You probably don't need this event, and found your way here because you looked at some code in an old plugin that
+ * abused it (very common). Instead of using custom player classes, you should consider making session classes instead.
+ *
+ * @see https://github.com/pmmp/SessionsDemo
+ *
+ * This event is a power-user feature, and multiple plugins using it at the same time will conflict and break unless
+ * they've been designed to work together. This means that it's only usually useful in private plugins.
+ *
+ * WARNING: This should NOT be used for adding extra functions or properties. This is intended for **overriding existing
+ * core behaviour**, and should only be used if you know EXACTLY what you're doing.
+ * Custom player classes may break in any update without warning. This event isn't much more than glorified reflection.
  */
 class PlayerCreationEvent extends Event{
 
@@ -54,6 +67,8 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Returns the base class that the final player class must extend.
+	 *
 	 * @return string
 	 * @phpstan-return class-string<Player>
 	 */
@@ -62,6 +77,10 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Sets the class that the final player class must extend.
+	 * The new base class must be a subclass of the current base class.
+	 * This can (perhaps) be used to limit the options for custom player classes provided by other plugins.
+	 *
 	 * @param string $class
 	 * @phpstan-param class-string<Player> $class
 	 */
@@ -74,6 +93,8 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Returns the class that will be instantiated to create the player after the event.
+	 *
 	 * @return string
 	 * @phpstan-return class-string<Player>
 	 */
@@ -82,6 +103,9 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Sets the class that will be instantiated to create the player after the event. The class must not be abstract,
+	 * and must be an instance of the base class.
+	 *
 	 * @param string $class
 	 * @phpstan-param class-string<Player> $class
 	 */