Update documentation of setParsed* and setRich*

Signed-off-by: Joas Schilling <coding@schilljs.com>

1 files changed, 42 insertions, 0 deletions

diff --git a/lib/public/Activity/IEvent.php b/lib/public/Activity/IEvent.php
index aee00039b65..e380eca5c24 100644
--- a/lib/public/Activity/IEvent.php
+++ b/lib/public/Activity/IEvent.php
@@ -100,6 +100,17 @@ interface IEvent {
 	public function setSubject(string $subject, array $parameters = []): self;
 
 	/**
+	 * Set a parsed subject
+	 *
+	 * HTML is not allowed in the parsed subject and will be escaped
+	 * automatically by the clients. You can use the RichObjectString system
+	 * provided by the Nextcloud server to highlight important parameters via
+	 * the setRichSubject method, but make sure, that a plain text message is
+	 * always set via setParsedSubject, to support clients which can not handle
+	 * rich strings.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
 	 * @param string $subject
 	 * @return $this
 	 * @throws \InvalidArgumentException if the subject is invalid
@@ -114,6 +125,16 @@ interface IEvent {
 	public function getParsedSubject(): string;
 
 	/**
+	 * Set a RichObjectString subject
+	 *
+	 * HTML is not allowed in the rich subject and will be escaped automatically
+	 * by the clients, but you can use the RichObjectString system provided by
+	 * the Nextcloud server to highlight important parameters.
+	 * Also make sure, that a plain text subject is always set via
+	 * setParsedSubject, to support clients which can not handle rich strings.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
 	 * @param string $subject
 	 * @param array $parameters
 	 * @return $this
@@ -146,6 +167,17 @@ interface IEvent {
 	public function setMessage(string $message, array $parameters = []): self;
 
 	/**
+	 * Set a parsed message
+	 *
+	 * HTML is not allowed in the parsed message and will be escaped
+	 * automatically by the clients. You can use the RichObjectString system
+	 * provided by the Nextcloud server to highlight important parameters via
+	 * the setRichMessage method, but make sure, that a plain text message is
+	 * always set via setParsedMessage, to support clients which can not handle
+	 * rich strings.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
 	 * @param string $message
 	 * @return $this
 	 * @throws \InvalidArgumentException if the message is invalid
@@ -160,6 +192,16 @@ interface IEvent {
 	public function getParsedMessage(): string;
 
 	/**
+	 * Set a RichObjectString message
+	 *
+	 * HTML is not allowed in the rich message and will be escaped automatically
+	 * by the clients, but you can use the RichObjectString system provided by
+	 * the Nextcloud server to highlight important parameters.
+	 * Also make sure, that a plain text message is always set via
+	 * setParsedMessage, to support clients which can not handle rich strings.
+	 *
+	 * See https://github.com/nextcloud/server/issues/1706 for more information.
+	 *
 	 * @param string $message
 	 * @param array $parameters
 	 * @return $this