Improve documentation of SourceInterface and AdvancedSourceInterface

src/pocketmine/network/AdvancedSourceInterface.php

@@ -26,15 +26,23 @@ declare(strict_types=1);
  */
 namespace pocketmine\network;
 
+/**
+ * Advanced network interfaces have some additional capabilities, such as being able to ban addresses and process raw
+ * packets.
+ */
 interface AdvancedSourceInterface extends SourceInterface{
 
 	/**
+	 * Prevents packets received from the IP address getting processed for the given timeout.
+	 *
 	 * @param string $address
 	 * @param int    $timeout Seconds
 	 */
 	public function blockAddress(string $address, int $timeout = 300);
 
 	/**
+	 * Unblocks a previously-blocked address.
+	 *
 	 * @param string $address
 	 */
 	public function unblockAddress(string $address);
@@ -45,6 +53,8 @@ interface AdvancedSourceInterface extends SourceInterface{
 	public function setNetwork(Network $network);
 
 	/**
+	 * Sends a raw payload to the network interface, bypassing any sessions.
+	 *
 	 * @param string $address
 	 * @param int    $port
 	 * @param string $payload

src/pocketmine/network/SourceInterface.php

@@ -30,7 +30,7 @@ use pocketmine\network\mcpe\protocol\DataPacket;
 use pocketmine\Player;
 
 /**
- * Classes that implement this interface will be able to be attached to players
+ * Network interfaces are transport layers which can be used to transmit packets between the server and clients.
  */
 interface SourceInterface{
 
@@ -69,10 +69,14 @@ interface SourceInterface{
 	 */
 	public function process() : void;
 
+	/**
+	 * Gracefully shuts down the network interface.
+	 */
 	public function shutdown();
 
 	/**
 	 * @deprecated
+	 * Shuts down the network interface in an emergency situation, such as due to a crash.
 	 */
 	public function emergencyShutdown();