From 3a373b880db59d3f55ba66c3ad28534988d56a66 Mon Sep 17 00:00:00 2001 From: "Dylan K. Taylor" Date: Thu, 12 Jul 2018 19:24:46 +0100 Subject: [PATCH] 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 | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/pocketmine/event/Listener.php b/src/pocketmine/event/Listener.php index e19f673c8..0a3f84f50 100644 --- a/src/pocketmine/event/Listener.php +++ b/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 `: 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{ }