diff --git a/src/pocketmine/event/player/PlayerJoinEvent.php b/src/pocketmine/event/player/PlayerJoinEvent.php
index e2441a7c6..36609ec82 100644
--- a/src/pocketmine/event/player/PlayerJoinEvent.php
+++ b/src/pocketmine/event/player/PlayerJoinEvent.php
@@ -27,7 +27,11 @@ use pocketmine\lang\TextContainer;
 use pocketmine\Player;
 
 /**
- * Called when a player joins the server, after sending all the spawn packets
+ * Called when the player spawns in the world after logging in, when they first see the terrain.
+ *
+ * Note: A lot of data is sent to the player between login and this event. Disconnecting the player during this event
+ * will cause this data to be wasted. Prefer disconnecting at login-time if possible to minimize bandwidth wastage.
+ * @see PlayerLoginEvent
  */
 class PlayerJoinEvent extends PlayerEvent{
 	/** @var string|TextContainer */
diff --git a/src/pocketmine/event/player/PlayerLoginEvent.php b/src/pocketmine/event/player/PlayerLoginEvent.php
index 90846d7b9..5afbaa061 100644
--- a/src/pocketmine/event/player/PlayerLoginEvent.php
+++ b/src/pocketmine/event/player/PlayerLoginEvent.php
@@ -27,7 +27,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\Player;
 
 /**
- * Called when a player joins, after things have been correctly set up (you can change anything now)
+ * Called after the player has successfully authenticated, before it spawns. The player is on the loading screen when
+ * this is called.
+ * Cancelling this event will cause the player to be disconnected with the kick message set.
  */
 class PlayerLoginEvent extends PlayerEvent implements Cancellable{
 	/** @var string */
diff --git a/src/pocketmine/event/player/PlayerPreLoginEvent.php b/src/pocketmine/event/player/PlayerPreLoginEvent.php
index f450268c8..6ad2ce22f 100644
--- a/src/pocketmine/event/player/PlayerPreLoginEvent.php
+++ b/src/pocketmine/event/player/PlayerPreLoginEvent.php
@@ -27,7 +27,17 @@ use pocketmine\event\Cancellable;
 use pocketmine\Player;
 
 /**
- * Called when the player logs in, before things have been set up
+ * Called when a player connects to the server, prior to authentication taking place.
+ * Cancelling this event will cause the player to be disconnected with the kick message set.
+ *
+ * This event should be used to decide if the player may continue to login to the server. Do things like checking
+ * bans, whitelisting, server-full etc here.
+ *
+ * WARNING: Any information about the player CANNOT be trusted at this stage, because they are not authenticated and
+ * could be a hacker posing as another player.
+ *
+ * WARNING: Due to internal bad architecture, the player is not fully constructed at this stage, and errors might occur
+ * when calling API methods on the player. Tread with caution.
  */
 class PlayerPreLoginEvent extends PlayerEvent implements Cancellable{
 	/** @var string */