Merge pull request #22168 from nextcloud/enh/noid/phpdoc-for-events

Add PHP doc for events

apps/files/lib/Event/LoadAdditionalScriptsEvent.php

@@ -28,6 +28,11 @@ namespace OCA\Files\Event;
 
 use OCP\EventDispatcher\Event;
 
+/**
+ * This event is triggered when the files app is rendered. It canb e used to add additional scripts to the files app.
+ *
+ * @since 17.0.0
+ */
 class LoadAdditionalScriptsEvent extends Event {
 	private $hiddenFields = [];
 

lib/public/Authentication/Events/LoginFailedEvent.php

@@ -29,9 +29,7 @@ namespace OCP\Authentication\Events;
 use OCP\EventDispatcher\Event;
 
 /**
- * Class LoginFailedEvent
- *
- * @package OCP\Authentication\Events
+ * Emitted when the authentication fails, but only if the login name can be associated with an existing user.
  *
  * @since 19.0.0
  */

lib/public/DirectEditing/RegisterDirectEditorEvent.php

@@ -26,6 +26,8 @@ namespace OCP\DirectEditing;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Event to allow to register the direct editor.
+ *
  * @since 18.0.0
  */
 class RegisterDirectEditorEvent extends Event {

lib/public/Mail/Events/BeforeMessageSent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\Mail\IMessage;
 
 /**
+ * Emitted before a system mail is sent. It can be used to alter the message.
+ *
  * @since 19.0.0
  */
 class BeforeMessageSent extends Event {

lib/public/Security/CSP/AddContentSecurityPolicyEvent.php

@@ -32,6 +32,16 @@ use OCP\AppFramework\Http\EmptyContentSecurityPolicy;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Allows to inject something into the default content policy. This is for
+ * example useful when you're injecting Javascript code into a view belonging
+ * to another controller and cannot modify its Content-Security-Policy itself.
+ * Note that the adjustment is only applied to applications that use AppFramework
+ * controllers.
+ *
+ * WARNING: Using this API incorrectly may make the instance more insecure.
+ * Do think twice before adding whitelisting resources. Please do also note
+ * that it is not possible to use the `disallowXYZ` functions.
+ *
  * @since 17.0.0
  */
 class AddContentSecurityPolicyEvent extends Event {

lib/public/Security/FeaturePolicy/AddFeaturePolicyEvent.php

@@ -32,6 +32,8 @@ use OCP\AppFramework\Http\EmptyFeaturePolicy;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Event that allows to register a feature policy header to a request.
+ *
  * @since 17.0.0
  */
 class AddFeaturePolicyEvent extends Event {

lib/public/User/Events/BeforePasswordUpdatedEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted before the user password is updated.
+ *
  * @since 18.0.0
  */
 class BeforePasswordUpdatedEvent extends Event {

lib/public/User/Events/BeforeUserCreatedEvent.php

@@ -29,6 +29,8 @@ namespace OCP\User\Events;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Emitted before a new user is created on the back-end.
+ *
  * @since 18.0.0
  */
 class BeforeUserCreatedEvent extends Event {

lib/public/User/Events/BeforeUserLoggedInWithCookieEvent.php

@@ -29,6 +29,8 @@ namespace OCP\User\Events;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Emitted before a user is logged in via remember-me cookies.
+ *
  * @since 18.0.0
  */
 class BeforeUserLoggedInWithCookieEvent extends Event {

lib/public/User/Events/BeforeUserLoggedOutEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted before a user is logged out.
+ *
  * @since 18.0.0
  */
 class BeforeUserLoggedOutEvent extends Event {

lib/public/User/Events/PasswordUpdatedEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted when the user password has been updated.
+ *
  * @since 18.0.0
  */
 class PasswordUpdatedEvent extends Event {

lib/public/User/Events/UserCreatedEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted when a new user has been created on the back-end.
+ *
  * @since 18.0.0
  */
 class UserCreatedEvent extends Event {

lib/public/User/Events/UserLoggedInWithCookieEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted when a user has been succesfully logged in via remember-me cookies.
+ *
  * @since 18.0.0
  */
 class UserLoggedInWithCookieEvent extends Event {

lib/public/User/Events/UserLoggedOutEvent.php

@@ -30,6 +30,8 @@ use OCP\EventDispatcher\Event;
 use OCP\IUser;
 
 /**
+ * Emitted when a user has been logged out successfully.
+ *
  * @since 18.0.0
  */
 class UserLoggedOutEvent extends Event {

lib/public/WorkflowEngine/Events/LoadSettingsScriptsEvent.php

@@ -28,6 +28,8 @@ namespace OCP\WorkflowEngine\Events;
 use OCP\EventDispatcher\Event;
 
 /**
+ * Emitted when the workflow engine settings page is loaded.
+ *
  * @since 20.0.0
  */
 class LoadSettingsScriptsEvent extends Event {