Merge branch 'stable' into next-minor

src/event/player/PlayerDropItemEvent.php

@@ -29,7 +29,7 @@ use pocketmine\item\Item;
 use pocketmine\player\Player;
 
 /**
- * Called when a player tries to drop an item from its hotbar
+ * Called when a player tries to drop an item
  */
 class PlayerDropItemEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;

src/event/player/PlayerItemHeldEvent.php

@@ -28,6 +28,11 @@ use pocketmine\event\CancellableTrait;
 use pocketmine\item\Item;
 use pocketmine\player\Player;
 
+/**
+ * Called when a player's held item changes.
+ * This could be because they selected a different hotbar slot, or because the item in the selected hotbar slot was
+ * changed.
+ */
 class PlayerItemHeldEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
 

src/event/player/PlayerKickEvent.php

@@ -29,7 +29,7 @@ use pocketmine\lang\Translatable;
 use pocketmine\player\Player;
 
 /**
- * Called when a player leaves the server
+ * Called when a player is kicked (forcibly disconnected) from the server, e.g. if an operator used /kick.
  */
 class PlayerKickEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
@@ -46,18 +46,33 @@ class PlayerKickEvent extends PlayerEvent implements Cancellable{
 		$this->reason = $reason;
 	}
 
+	/**
+	 * Sets the message shown on the kicked player's disconnection screen.
+	 * This message is also displayed in the console and server log.
+	 */
 	public function setReason(string $reason) : void{
 		$this->reason = $reason;
 	}
 
+	/**
+	 * Returns the message shown on the kicked player's disconnection screen.
+	 * This message is also displayed in the console and server log.
+	 * When kicked by the /kick command, the default is something like "Kicked by admin.".
+	 */
 	public function getReason() : string{
 		return $this->reason;
 	}
 
+	/**
+	 * Sets the quit message broadcasted to other players.
+	 */
 	public function setQuitMessage(Translatable|string $quitMessage) : void{
 		$this->quitMessage = $quitMessage;
 	}
 
+	/**
+	 * Returns the quit message broadcasted to other players, e.g. "Steve left the game".
+	 */
 	public function getQuitMessage() : Translatable|string{
 		return $this->quitMessage;
 	}

src/event/player/PlayerQuitEvent.php

@@ -27,7 +27,14 @@ use pocketmine\lang\Translatable;
 use pocketmine\player\Player;
 
 /**
- * Called when a player leaves the server
+ * Called when a player disconnects from the server for any reason.
+ *
+ * Some possible reasons include:
+ * - being kicked by an operator
+ * - disconnecting from the game
+ * - timeout due to network connectivity issues
+ *
+ * @see PlayerKickEvent
  */
 class PlayerQuitEvent extends PlayerEvent{
 
@@ -42,14 +49,23 @@ class PlayerQuitEvent extends PlayerEvent{
 		$this->quitReason = $quitReason;
 	}
 
+	/**
+	 * Sets the quit message broadcasted to other players.
+	 */
 	public function setQuitMessage(Translatable|string $quitMessage) : void{
 		$this->quitMessage = $quitMessage;
 	}
 
+	/**
+	 * Returns the quit message broadcasted to other players, e.g. "Steve left the game".
+	 */
 	public function getQuitMessage() : Translatable|string{
 		return $this->quitMessage;
 	}
 
+	/**
+	 * Returns the disconnect reason shown in the server log and on the console.
+	 */
 	public function getQuitReason() : string{
 		return $this->quitReason;
 	}

src/event/player/PlayerTransferEvent.php

@@ -27,6 +27,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 use pocketmine\player\Player;
 
+/**
+ * Called when a player attempts to be transferred to another server, e.g. by using /transferserver.
+ */
 class PlayerTransferEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
 
@@ -44,26 +47,44 @@ class PlayerTransferEvent extends PlayerEvent implements Cancellable{
 		$this->message = $message;
 	}
 
+	/**
+	 * Returns the destination server address. This could be an IP or a domain name.
+	 */
 	public function getAddress() : string{
 		return $this->address;
 	}
 
+	/**
+	 * Sets the destination server address.
+	 */
 	public function setAddress(string $address) : void{
 		$this->address = $address;
 	}
 
+	/**
+	 * Returns the destination server port.
+	 */
 	public function getPort() : int{
 		return $this->port;
 	}
 
+	/**
+	 * Sets the destination server port.
+	 */
 	public function setPort(int $port) : void{
 		$this->port = $port;
 	}
 
+	/**
+	 * Returns the disconnect reason shown in the server log and on the console.
+	 */
 	public function getMessage() : string{
 		return $this->message;
 	}
 
+	/**
+	 * Sets the disconnect reason shown in the server log and on the console.
+	 */
 	public function setMessage(string $message) : void{
 		$this->message = $message;
 	}