5 files changed, 28 insertions, 6 deletions
diff --git a/lib/public/Dashboard/IAPIWidget.php b/lib/public/Dashboard/IAPIWidget.php
index 8fec40cf1b1..c8f98290a0e 100644
--- a/lib/public/Dashboard/IAPIWidget.php
+++ b/lib/public/Dashboard/IAPIWidget.php
@@ -9,6 +9,8 @@ declare(strict_types=1);
 
 namespace OCP\Dashboard;
 
+use OCP\Dashboard\Model\WidgetItem;
+
 /**
  * interface IAPIWidget
  *
@@ -16,7 +18,7 @@ namespace OCP\Dashboard;
  */
 interface IAPIWidget extends IWidget {
 	/**
-	 * @return \OCP\Dashboard\Model\WidgetItem[] The widget items
+	 * @return list<WidgetItem> The widget items
 	 * @since 22.0.0
 	 */
 	public function getItems(string $userId, ?string $since = null, int $limit = 7): array;
diff --git a/lib/public/Dashboard/IButtonWidget.php b/lib/public/Dashboard/IButtonWidget.php
index fa8d6bc36a6..f4ebd9253c7 100644
--- a/lib/public/Dashboard/IButtonWidget.php
+++ b/lib/public/Dashboard/IButtonWidget.php
@@ -19,7 +19,7 @@ interface IButtonWidget extends IWidget {
 	 * Get the buttons to show on the widget
 	 *
 	 * @param string $userId
-	 * @return WidgetButton[]
+	 * @return list<WidgetButton>
 	 * @since 25.0.0
 	 */
 	public function getWidgetButtons(string $userId): array;
diff --git a/lib/public/Dashboard/IIconWidget.php b/lib/public/Dashboard/IIconWidget.php
index c6cfd03e0ff..203a89279b0 100644
--- a/lib/public/Dashboard/IIconWidget.php
+++ b/lib/public/Dashboard/IIconWidget.php
@@ -14,7 +14,9 @@ namespace OCP\Dashboard;
  */
 interface IIconWidget extends IWidget {
 	/**
-	 * Get the absolute url for the widget icon
+	 * Get the absolute url for the widget icon (should be colored black or not have a color)
+	 *
+	 * The icon will be inverted automatically in mobile clients and when using dark mode
 	 *
 	 * @return string
 	 * @since 25.0.0
diff --git a/lib/public/Dashboard/IWidget.php b/lib/public/Dashboard/IWidget.php
index 134758f02c6..c6bac98cae2 100644
--- a/lib/public/Dashboard/IWidget.php
+++ b/lib/public/Dashboard/IWidget.php
@@ -15,7 +15,12 @@ namespace OCP\Dashboard;
  */
 interface IWidget {
 	/**
-	 * @return string Unique id that identifies the widget, e.g. the app id
+	 * Get a unique identifier for the widget
+	 *
+	 * To ensure uniqueness, it is recommended to user the app id or start with the
+	 * app id followed by a dash.
+	 *
+	 * @return string Unique id that identifies the widget, e.g. the app id. Only use alphanumeric characters, dash and underscore
 	 * @since 20.0.0
 	 */
 	public function getId(): string;
@@ -33,6 +38,13 @@ interface IWidget {
 	public function getOrder(): int;
 
 	/**
+	 * CSS class that shows the widget icon (should be colored black or not have a color)
+	 *
+	 * The icon will be inverted automatically in mobile clients and when using dark mode.
+	 * Therefore, it is NOT recommended to use a css class that sets the background with:
+	 * `var(--icon-…)` as those will adapt to dark/bright mode in the web and still be inverted
+	 * resulting in a dark icon on dark background.
+	 *
 	 * @return string css class that displays an icon next to the widget title
 	 * @since 20.0.0
 	 */
diff --git a/lib/public/Dashboard/Model/WidgetItem.php b/lib/public/Dashboard/Model/WidgetItem.php
index be5fba82323..680daf1b114 100644
--- a/lib/public/Dashboard/Model/WidgetItem.php
+++ b/lib/public/Dashboard/Model/WidgetItem.php
@@ -134,8 +134,14 @@ final class WidgetItem implements JsonSerializable {
 
 	/**
 	 * @since 22.0.0
-	 *
-	 * @return array
+	 * @return array{
+	 *      subtitle: string,
+	 *      title: string,
+	 *      link: string,
+	 *      iconUrl: string,
+	 *      overlayIconUrl: string,
+	 *      sinceId: string,
+	 *  }
 	 */
 	public function jsonSerialize(): array {
 		return [