Listener: Add documentation on functionality (#2292)

The Listener interface is one of the most magical parts of PocketMine-MP, and before this pull request it didn't have a single bit of documentation.

src/pocketmine/event/Listener.php

@@ -23,6 +23,37 @@ declare(strict_types=1);
 
 namespace pocketmine\event;
 
+use pocketmine\plugin\PluginManager;
+
+/**
+ * Classes implementing this interface can be registered to receive called Events.
+ * @see PluginManager::registerEvents()
+ *
+ * A function in a Listener class must meet the following criteria to be registered as an event handler:
+ *
+ * - MUST be public
+ * - MUST NOT be static
+ * - MUST accept EXACTLY ONE class parameter which:
+ *   - MUST be a VALID class extending Event
+ *   - MUST NOT be abstract, UNLESS it has an `@allowHandle` annotation
+ *
+ * Event handlers do not have to have any particular name - they are detected using reflection.
+ * They SHOULD NOT return any values (but this is not currently enforced).
+ *
+ * Functions which meet the criteria can have the following annotations in their doc comments:
+ *
+ * - `@notHandler`: Marks a function as NOT being an event handler. Only needed if the function meets the above criteria.
+ * - `@softDepend [PluginName]`: Handler WILL NOT be registered if its event doesn't exist. Useful for soft-depending
+ *     on plugin events. Plugin name is optional.
+ *     Example: `@softDepend SimpleAuth`
+ * - `@ignoreCancelled`: Cancelled events WILL NOT be passed to this handler.
+ * - `@priority <PRIORITY>`: Sets the priority at which this event handler will receive events.
+ *     Example: `@priority HIGHEST`
+ *     @see EventPriority for a list of possible options.
+ *
+ * Event handlers will receive any instanceof the Event class they have chosen to receive. For example, an
+ * EntityDamageEvent handler will also receive any subclass of EntityDamageEvent.
+ */
 interface Listener{
 
 }