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/Notification/INotification.php b/lib/public/Notification/INotification.php
index 58f05883450..29f2a0e7943 100644
--- a/lib/public/Notification/INotification.php
+++ b/lib/public/Notification/INotification.php
@@ -115,6 +115,17 @@ interface INotification {
 	public function getSubjectParameters();
 
 	/**
+	 * 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
@@ -129,6 +140,16 @@ interface INotification {
 	public function getParsedSubject();
 
 	/**
+	 * 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
@@ -171,6 +192,17 @@ interface INotification {
 	public function getMessageParameters();
 
 	/**
+	 * 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
@@ -185,6 +217,16 @@ interface INotification {
 	public function getParsedMessage();
 
 	/**
+	 * 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