Consistent API docs, #PG-5079 (#76)

* docs: updated API documentation to be more consistent

* Updated changelog

Author: lachiebol

API.php

@@ -15,9 +15,9 @@
 use Piwik\Plugin;
 
 /**
- * The Provider API lets you access reports for your visitors Internet Providers.
+ * Exposes reporting endpoints for visitor internet provider and ISP data.
  *
- * The main report groups visits by resolved ISP hostname and provider label.
+ * Reports group visits by resolved provider hostname and display label.
  *
  * @method static \Piwik\Plugins\Provider\API getInstance()
  */
@@ -30,17 +30,15 @@ class API extends \Piwik\Plugin\API
      *                                 - Single site ID (e.g. 1)
      *                                 - Multiple site IDs (e.g. [1, 4, 5])
      *                                 - Comma-separated list ("1,4,5") or "all"
-     * @param string $period The period to process, processes data for the period containing the specified date.
-     *                       Allowed values: "day", "week", "month", "year", "range".
-     * @param string|\Piwik\Date $date The date or date range to process.
-     *                                 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear),
-     *                                 or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
-     * @param string|false $segment (Optional) Custom segment to filter the report.
-     *                              Example: "referrerName==twitter.com"
-     *                              Supports AND (;) and OR (,) operators.
-     *                              [See documentation](https://developer.matomo.org/api-reference/reporting-api-segmentation)
+     * @param 'day'|'week'|'month'|'year'|'range' $period The period to process, processes data for the period
+     *                                                    containing the specified date.
+     * @param string $date The date or date range to process.
+     *                     'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear),
+     *                     or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX).
+     * @param string|null|false $segment Custom segment to filter the report.
+     *                                   Example: "referrerName==example.com"
+     *                                   Supports AND (;) and OR (,) operators.
      * @return \Piwik\DataTable|\Piwik\DataTable\Map Provider metrics by internet provider label.
-     * @throws \Exception If the current user does not have view access to the requested site(s).
      */
     public function getProvider($idSite, $period, $date, $segment = false)
     {

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Changelog
 
+### 5.0.5
+* 27/04/2026 Updated API documentation
+
 ### 5.0.5
 * 02/03/2026 Updated API documentation
 

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "Provider",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Reports the Internet Service Provider of the visitors.",
   "theme": false,
   "keywords": ["provider", "internet", "service", "report"],