Merge branch 'stable' into next-minor

src/event/entity/EntityDespawnEvent.php

@@ -26,7 +26,9 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\Entity;
 
 /**
- * Called when a entity is despawned
+ * Called when an entity is removed from the world. This could be for a variety of reasons, including chunks being
+ * unloaded, entity death, etc.
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntityDespawnEvent extends EntityEvent{

src/event/entity/EntityExplodeEvent.php

@@ -31,7 +31,11 @@ use pocketmine\utils\Utils;
 use pocketmine\world\Position;
 
 /**
- * Called when a entity explodes
+ * Called when an entity explodes, after the explosion's impact has been calculated.
+ * No changes have been made to the world at this stage.
+ *
+ * @see ExplosionPrimeEvent
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntityExplodeEvent extends EntityEvent implements Cancellable{
@@ -47,12 +51,16 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	protected $yield;
 
 	/**
-	 * @param Block[]  $blocks
+	 * @param Block[] $blocks
+	 * @param float   $yield 0-100
 	 */
 	public function __construct(Entity $entity, Position $position, array $blocks, float $yield){
 		$this->entity = $entity;
 		$this->position = $position;
 		$this->blocks = $blocks;
+		if($yield < 0.0 || $yield > 100.0){
+			throw new \InvalidArgumentException("Yield must be in range 0.0 - 100.0");
+		}
 		$this->yield = $yield;
 	}
 
@@ -61,6 +69,8 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	}
 
 	/**
+	 * Returns a list of blocks destroyed by the explosion.
+	 *
 	 * @return Block[]
 	 */
 	public function getBlockList() : array{
@@ -68,6 +78,8 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	}
 
 	/**
+	 * Sets the blocks destroyed by the explosion.
+	 *
 	 * @param Block[] $blocks
 	 */
 	public function setBlockList(array $blocks) : void{
@@ -75,11 +87,22 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 		$this->blocks = $blocks;
 	}
 
+	/**
+	 * Returns the percentage chance of drops from each block destroyed by the explosion.
+	 * @return float 0-100
+	 */
 	public function getYield() : float{
 		return $this->yield;
 	}
 
+	/**
+	 * Sets the percentage chance of drops from each block destroyed by the explosion.
+	 * @param float $yield 0-100
+	 */
 	public function setYield(float $yield) : void{
+		if($yield < 0.0 || $yield > 100.0){
+			throw new \InvalidArgumentException("Yield must be in range 0.0 - 100.0");
+		}
 		$this->yield = $yield;
 	}
 }

src/event/entity/EntitySpawnEvent.php

@@ -26,7 +26,8 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\Entity;
 
 /**
- * Called when a entity is spawned
+ * Called when an entity is added to the world. This might be a new entity or an entity loaded from storage.
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntitySpawnEvent extends EntityEvent{

src/event/entity/ExplosionPrimeEvent.php

@@ -28,7 +28,11 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a entity decides to explode
+ * Called when an entity decides to explode, before the explosion's impact is calculated.
+ * This allows changing the force of the explosion and whether it will destroy blocks.
+ *
+ * @see EntityExplodeEvent
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
@@ -39,6 +43,9 @@ class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	private bool $blockBreaking = true;
 
 	public function __construct(Entity $entity, float $force){
+		if($force <= 0){
+			throw new \InvalidArgumentException("Explosion radius must be positive");
+		}
 		$this->entity = $entity;
 		$this->force = $force;
 	}
@@ -48,6 +55,9 @@ class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	}
 
 	public function setForce(float $force) : void{
+		if($force <= 0){
+			throw new \InvalidArgumentException("Explosion radius must be positive");
+		}
 		$this->force = $force;
 	}
 

src/event/entity/ItemDespawnEvent.php

@@ -28,6 +28,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
+ * Called when a dropped item tries to despawn due to its despawn delay running out.
+ * Cancelling the event will reset the despawn delay to default (5 minutes).
+ *
  * @phpstan-extends EntityEvent<ItemEntity>
  */
 class ItemDespawnEvent extends EntityEvent implements Cancellable{

src/event/entity/ItemSpawnEvent.php

@@ -26,6 +26,15 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\object\ItemEntity;
 
 /**
+ * Called when an item is spawned or loaded.
+ *
+ * Some possible reasons include:
+ * - item is loaded from disk
+ * - player dropping an item
+ * - block drops
+ * - loot of a player or entity
+ *
+ * @see PlayerDropItemEvent
  * @phpstan-extends EntityEvent<ItemEntity>
  */
 class ItemSpawnEvent extends EntityEvent{

src/event/inventory/InventoryTransactionEvent.php

@@ -29,8 +29,17 @@ use pocketmine\event\Event;
 use pocketmine\inventory\transaction\InventoryTransaction;
 
 /**
- * Called when there is a transaction between two Inventory objects.
- * The source of this can be a Player, entities, mobs, or even hoppers in the future!
+ * Called when a player performs actions involving items in inventories.
+ *
+ * This may involve multiple inventories, and may include actions such as:
+ * - moving items from one slot to another
+ * - splitting itemstacks
+ * - dragging itemstacks across inventory slots (slot painting)
+ * - dropping an item on the ground
+ * - taking an item from the creative inventory menu
+ * - destroying (trashing) an item
+ *
+ * @see https://doc.pmmp.io/en/rtfd/developer-reference/inventory-transactions.html for more information on inventory transactions
  */
 class InventoryTransactionEvent extends Event implements Cancellable{
 	use CancellableTrait;

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;
 	}

src/event/server/CommandEvent.php

@@ -28,12 +28,18 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when any CommandSender runs a command, early in the process
+ * Called when any CommandSender runs a command, before it is parsed.
  *
- * You don't want to use this except for a few cases like logging commands,
- * blocking commands on certain places, or applying modifiers.
+ * This can be used for logging commands, or preprocessing the command string to add custom features (e.g. selectors).
  *
- * The message DOES NOT contain a slash at the start
+ * WARNING: DO NOT use this to block commands. Many commands have aliases.
+ * For example, /version can also be invoked using /ver or /about.
+ * To prevent command senders from using certain commands, deny them permission to use the commands you don't want them
+ * to have access to.
+ *
+ * @see Permissible::addAttachment()
+ *
+ * The message DOES NOT begin with a slash.
  */
 class CommandEvent extends ServerEvent implements Cancellable{
 	use CancellableTrait;

src/event/server/UpdateNotifyEvent.php

@@ -26,7 +26,7 @@ namespace pocketmine\event\server;
 use pocketmine\updater\UpdateChecker;
 
 /**
- * Called when the AutoUpdater receives notification of an available PocketMine-MP update.
+ * Called when the update checker receives notification of an available PocketMine-MP update.
  * Plugins may use this event to perform actions when an update notification is received.
  */
 class UpdateNotifyEvent extends ServerEvent{

src/event/world/ChunkLoadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\world\format\Chunk;
 use pocketmine\world\World;
 
 /**
- * Called when a Chunk is loaded
+ * Called when a Chunk is loaded or newly created by the world generator.
  */
 class ChunkLoadEvent extends ChunkEvent{
 	public function __construct(
@@ -40,6 +40,10 @@ class ChunkLoadEvent extends ChunkEvent{
 		parent::__construct($world, $chunkX, $chunkZ, $chunk);
 	}
 
+	/**
+	 * Returns whether the chunk is newly generated.
+	 * If false, the chunk was loaded from storage.
+	 */
 	public function isNewChunk() : bool{
 		return $this->newChunk;
 	}

src/event/world/ChunkPopulateEvent.php

@@ -24,7 +24,8 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a Chunk is populated (after receiving it on the main thread)
+ * Called when a Chunk is fully populated by the world generator.
+ * This means that the terrain has been generated, and all artifacts (e.g. trees, grass, ponds, etc.) have been placed.
  */
 class ChunkPopulateEvent extends ChunkEvent{
 

src/event/world/ChunkUnloadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a Chunk is unloaded
+ * Called when a Chunk is unloaded from memory.
  */
 class ChunkUnloadEvent extends ChunkEvent implements Cancellable{
 	use CancellableTrait;

src/event/world/WorldInitEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is initializing
+ * Called when a new world is created/generated.
  */
 class WorldInitEvent extends WorldEvent{
 

src/event/world/WorldLoadEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is loaded
+ * Called when a world is loaded or newly created/generated.
  */
 class WorldLoadEvent extends WorldEvent{
 

src/event/world/WorldSaveEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is saved
+ * Called when a world is saved. Saving may be triggered manually (e.g. via commands) or automatically (autosave).
  */
 class WorldSaveEvent extends WorldEvent{
 

src/event/world/WorldUnloadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a World is unloaded
+ * Called when a world is unloaded from memory.
  */
 class WorldUnloadEvent extends WorldEvent implements Cancellable{
 	use CancellableTrait;