From 351cd4bfd7fd2e6e06b741717429bee51fa35022 Mon Sep 17 00:00:00 2001
From: "Dylan K. Taylor" <dktapps@pmmp.io>
Date: Sat, 21 May 2022 21:46:53 +0100
Subject: [PATCH] Improve documentation of world-related events

---
 src/event/world/ChunkLoadEvent.php     | 6 +++++-
 src/event/world/ChunkPopulateEvent.php | 3 ++-
 src/event/world/ChunkUnloadEvent.php   | 2 +-
 src/event/world/WorldInitEvent.php     | 2 +-
 src/event/world/WorldLoadEvent.php     | 2 +-
 src/event/world/WorldSaveEvent.php     | 2 +-
 src/event/world/WorldUnloadEvent.php   | 2 +-
 7 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/event/world/ChunkLoadEvent.php b/src/event/world/ChunkLoadEvent.php
index f8f1ef776..affc43a31 100644
--- a/src/event/world/ChunkLoadEvent.php
+++ b/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{
 	/** @var bool */
@@ -38,6 +38,10 @@ class ChunkLoadEvent extends ChunkEvent{
 		$this->newChunk = $newChunk;
 	}
 
+	/**
+	 * Returns whether the chunk is newly generated.
+	 * If false, the chunk was loaded from storage.
+	 */
 	public function isNewChunk() : bool{
 		return $this->newChunk;
 	}
diff --git a/src/event/world/ChunkPopulateEvent.php b/src/event/world/ChunkPopulateEvent.php
index 3797bb58b..c86ab9761 100644
--- a/src/event/world/ChunkPopulateEvent.php
+++ b/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{
 
diff --git a/src/event/world/ChunkUnloadEvent.php b/src/event/world/ChunkUnloadEvent.php
index 89b58b6d4..41b70ab3a 100644
--- a/src/event/world/ChunkUnloadEvent.php
+++ b/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;
diff --git a/src/event/world/WorldInitEvent.php b/src/event/world/WorldInitEvent.php
index 4b85571ed..238da6087 100644
--- a/src/event/world/WorldInitEvent.php
+++ b/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{
 
diff --git a/src/event/world/WorldLoadEvent.php b/src/event/world/WorldLoadEvent.php
index 18235c29b..6e8264300 100644
--- a/src/event/world/WorldLoadEvent.php
+++ b/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{
 
diff --git a/src/event/world/WorldSaveEvent.php b/src/event/world/WorldSaveEvent.php
index e43894791..43437d0c3 100644
--- a/src/event/world/WorldSaveEvent.php
+++ b/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{
 
diff --git a/src/event/world/WorldUnloadEvent.php b/src/event/world/WorldUnloadEvent.php
index 7f5b3ff8b..a8e226cae 100644
--- a/src/event/world/WorldUnloadEvent.php
+++ b/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;