Add PhpDoc headers to all components

diff --git a/wcfsetup/install/files/lib/action/ApiAction.class.php b/wcfsetup/install/files/lib/action/ApiAction.class.php
index 3ca436178807369eccd56384b5c8a9f5702448fa..3cb7348507af53eb05c1b1f5fb85dbdbf2c14bf5 100644 (file)
--- a/wcfsetup/install/files/lib/action/ApiAction.class.php
+++ b/wcfsetup/install/files/lib/action/ApiAction.class.php
@@ -22,6 +22,15 @@ use wcf\system\request\RouteHandler;
 
 use function FastRoute\simpleDispatcher;
 
+/**
+ * Resolves and forwards API requests to the responsible controllers, exposing
+ * a unified JSON-based response with a clearly defined behavior.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[AllowHttpMethod('DELETE')]
 final class ApiAction implements RequestHandlerInterface
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/DeleteRequest.class.php b/wcfsetup/install/files/lib/system/endpoint/DeleteRequest.class.php
index 803525078d50cd007d3d198be4407e190ad51ccc..b415242bdc8251512e2cc3c2be91580089757b1c 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/DeleteRequest.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/DeleteRequest.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Shortcut attribute for API endpoints using DELETE.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class DeleteRequest extends RequestType
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/GetRequest.class.php b/wcfsetup/install/files/lib/system/endpoint/GetRequest.class.php
index 69e63e9824413122c66e1ade4dc87db8d1272a2d..8a87f73413fc3da4ca5d550099fe1350785bb4e7 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/GetRequest.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/GetRequest.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Shortcut attribute for API endpoints using GET.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class GetRequest extends RequestType
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/IController.class.php b/wcfsetup/install/files/lib/system/endpoint/IController.class.php
index 2d34af7a5bb097b42d2d96a8b97e6b9e3357ce40..de0d9e71ec61391c95db9523192dc6737bdcd9df 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/IController.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/IController.class.php
@@ -6,9 +6,21 @@ use CuyZ\Valinor\Mapper\MappingError;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Handles incoming API requests, relying on the `RequestType` attributes to
+ * register the endpoint. The endpoint can contain placeholders for parameters.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 interface IController
 {
     /**
+     * Invokes the controller, passing in any placeholders from the endpoint in
+     * the `$variables` array.
+     *
      * @param array<string, string> $variables
      * @throws MappingError
      */

diff --git a/wcfsetup/install/files/lib/system/endpoint/PostRequest.class.php b/wcfsetup/install/files/lib/system/endpoint/PostRequest.class.php
index dc3820691400bb1fa9cc66ca9412396c83e7f291..d5ead97acecc3a4ec8b2744cd9a81057371360d5 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/PostRequest.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/PostRequest.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Shortcut attribute for API endpoints using POST.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class PostRequest extends RequestType
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/RequestFailure.class.php b/wcfsetup/install/files/lib/system/endpoint/RequestFailure.class.php
index 2f8dfb8d6538442761874dd1810a02fbc10adc30..40ba065f252587484c2318f1baa4cdba4eb8e246 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/RequestFailure.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/RequestFailure.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Represents different classes of errors for API endpoints.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 enum RequestFailure
 {
     case InternalError;

diff --git a/wcfsetup/install/files/lib/system/endpoint/RequestMethod.class.php b/wcfsetup/install/files/lib/system/endpoint/RequestMethod.class.php
index 3ce4142fe44375ec5f8483de6195707610a8ef9f..c96e3fe0bf6bfc00421aaabc95a416ef87d5e66a 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/RequestMethod.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/RequestMethod.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Represents the supported HTTP verbs for API endpoints.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 enum RequestMethod
 {
     case DELETE;

diff --git a/wcfsetup/install/files/lib/system/endpoint/RequestType.class.php b/wcfsetup/install/files/lib/system/endpoint/RequestType.class.php
index 64e32243581c5b58b9a2b4d37473a9b90d770ad5..ea1c6f5b52b0f3162fdc29aae76789e973684d17 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/RequestType.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/RequestType.class.php
@@ -2,6 +2,14 @@
 
 namespace wcf\system\endpoint;
 
+/**
+ * Defines the HTTP verb and route of an API endpoint.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class RequestType
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/controller/core/messages/MentionSuggestions.class.php b/wcfsetup/install/files/lib/system/endpoint/controller/core/messages/MentionSuggestions.class.php
index 4312463f3d59f4dffa1e9bb5d1e8b1527b0c4dd0..ea3d267dfe2a57e3b11d65ab56bf2e42d5ed9f22 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/controller/core/messages/MentionSuggestions.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/controller/core/messages/MentionSuggestions.class.php
@@ -10,8 +10,17 @@ use wcf\data\user\UserProfileList;
 use wcf\http\Helper;
 use wcf\system\endpoint\GetRequest;
 use wcf\system\endpoint\IController;
+use wcf\system\exception\UserInputException;
 use wcf\system\WCF;
 
+/**
+ * Retrieves the list of users and groups that can be mentioned.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[GetRequest('/core/messages/mentionsuggestions')]
 final class MentionSuggestions implements IController
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/controller/core/sessions/DeleteSession.class.php b/wcfsetup/install/files/lib/system/endpoint/controller/core/sessions/DeleteSession.class.php
index 2920e40d73acf66fca7d244b55822743c8a16a33..607f45199a2d36ea56105f79da9ab9b7f2f8c288 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/controller/core/sessions/DeleteSession.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/controller/core/sessions/DeleteSession.class.php
@@ -11,6 +11,15 @@ use wcf\system\exception\UserInputException;
 use wcf\system\session\SessionHandler;
 use wcf\system\WCF;
 
+/**
+ * Deletes one of the current user’s sessions, causing a device with that
+ * session id to be logged out.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 #[DeleteRequest('/core/sessions/{id}')]
 final class DeleteSession implements IController
 {

diff --git a/wcfsetup/install/files/lib/system/endpoint/event/ControllerCollecting.class.php b/wcfsetup/install/files/lib/system/endpoint/event/ControllerCollecting.class.php
index 73a2b5364c23d4fc63595513f9ce4d761777df1f..ab1914c092107f7e6b4c8034efc7dab26fb29b1a 100644 (file)
--- a/wcfsetup/install/files/lib/system/endpoint/event/ControllerCollecting.class.php
+++ b/wcfsetup/install/files/lib/system/endpoint/event/ControllerCollecting.class.php
@@ -5,6 +5,14 @@ namespace wcf\system\endpoint\event;
 use wcf\system\endpoint\IController;
 use wcf\system\event\IEvent;
 
+/**
+ * Collects the list of API controllers.
+ *
+ * @author Alexander Ebert
+ * @copyright 2001-2024 WoltLab GmbH
+ * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since 6.1
+ */
 final class ControllerCollecting implements IEvent
 {
     /**