From 4b89f5b7c44068b7fe0a7ba4ef0ccd7e7dfb8d4c Mon Sep 17 00:00:00 2001
From: sgiehl <stefan@matomo.org>
Date: Fri, 27 Mar 2026 17:00:01 +0100
Subject: [PATCH] Update API documentation for Tour

---
 plugins/Tour/API.php | 47 ++++++++++++++++++++++++++++----------------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/plugins/Tour/API.php b/plugins/Tour/API.php
index 971e07348c4..e4d4705a5d7 100644
--- a/plugins/Tour/API.php
+++ b/plugins/Tour/API.php
@@ -14,7 +14,7 @@
 use Piwik\Plugins\Tour\Engagement\Challenges;
 
 /**
- * API for Tour plugin which helps you getting familiar with Matomo.
+ * Provides API methods for Tour challenges and engagement levels.
  *
  * @method static \Piwik\Plugins\Tour\API getInstance()
  */
@@ -26,11 +26,10 @@ class API extends \Piwik\Plugin\API
     private $challenges;
 
     /**
-     * Levels
+     * @var Levels
      */
     private $levels;
 
-
     public function __construct(Challenges $challenges, Levels $levels)
     {
         $this->challenges = $challenges;
@@ -38,15 +37,22 @@ public function __construct(Challenges $challenges, Levels $levels)
     }
 
     /**
-     * Get all challenges that can be completed by a super user.
+     * Returns the available Tour challenges for the current super user.
      *
-     * @return array[]
+     * @return list<array{
+     *     id: string,
+     *     name: string,
+     *     description: string,
+     *     isCompleted: bool,
+     *     isSkipped: bool,
+     *     url: string
+     * }> Tour challenge metadata including completion and skip state.
      */
-    public function getChallenges()
+    public function getChallenges(): array
     {
         Piwik::checkUserHasSuperUserAccess();
 
-        $challenges = array();
+        $challenges = [];
 
         $login = Piwik::getCurrentUserLogin();
 
@@ -69,13 +75,12 @@ public function getChallenges()
     }
 
     /**
-     * Skip a specific challenge.
+     * Marks the specified Tour challenge as skipped for the current super user.
      *
-     * @param string $id
-     * @return bool
-     * @throws \Exception
+     * @param string $id The challenge ID to skip.
+     * @return true Returns `true` when the challenge was skipped successfully.
      */
-    public function skipChallenge($id)
+    public function skipChallenge(string $id): bool
     {
         Piwik::checkUserHasSuperUserAccess();
 
@@ -96,20 +101,28 @@ public function skipChallenge($id)
     }
 
     /**
-     * Get details about the current level this user has progressed to.
-     * @return array
+     * Returns the current Tour level details for the current super user.
+     *
+     * @return array{
+     *     description: string,
+     *     currentLevel: int,
+     *     currentLevelName: string,
+     *     nextLevelName: string|null,
+     *     numLevelsTotal: int,
+     *     challengesNeededForNextLevel: int
+     * } Tour level details including the current and next level names.
      */
-    public function getLevel()
+    public function getLevel(): array
     {
         Piwik::checkUserHasSuperUserAccess();
 
-        return array(
+        return [
             'description' => $this->levels->getCurrentDescription(),
             'currentLevel' => $this->levels->getCurrentLevel(),
             'currentLevelName' => $this->levels->getCurrentLevelName(),
             'nextLevelName' => $this->levels->getNextLevelName(),
             'numLevelsTotal' => $this->levels->getNumLevels(),
             'challengesNeededForNextLevel' => $this->levels->getNumChallengesNeededToNextLevel(),
-        );
+        ];
     }
 }