Removed setCancelled from Cancellable (#3685)

* Removed `setCancelled` from `Cancellable`

Before anyone screams, THIS CHANGE WILL NOT AFFECT MOST PLUGINS
(although it allows future changes to break some).

This commit rewrites the documentation of `Cancellable`,
clarifying the concept of "cancelled" from the perspective of the event
framework.

This commit also removes the `setCancelled` method from `Cancellable`.
This does not affect plugins using the (originally standard)
`setCancelled` method on events directly, since the implementation on
classes was not removed. On the other hand, it no longer requires
`Cancellable` events to implement this method, allowing flexibility on
cancelation conditions, e.g. subclasses may require additional
parameters for cancellation without needing to use hacks to check that
the user cancelled the event in the correct way.

src/event/Cancellable.php

@@ -24,10 +24,18 @@ declare(strict_types=1);
 namespace pocketmine\event;
 
 /**
- * Events that can be cancelled must use the interface Cancellable
+ * This interface is implemented by an Event subclass if and only if it can be cancelled.
+ *
+ * The cancellation of an event directly affects whether downstream event handlers
+ * without `@handleCancelled` will be called with this event.
+ * Implementations may provide a direct setter for cancellation (typically by using `CancellableTrait`)
+ * or implement an alternative logic (such as a function on another data field) for `isCancelled()`.
  */
 interface Cancellable{
+	/**
+	 * Returns whether this instance of the event is currently cancelled.
+	 *
+	 * If it is cancelled, only downstream handlers that declare `@handleCancelled` will be called with this event.
+	 */
 	public function isCancelled() : bool;
-
-	public function setCancelled(bool $value = true) : void;
 }