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

* docs: updated API documentation to be more consistent

* Updated changelog

* Update CHANGELOG.md

Co-authored-by: Altamash Shaikh <altamash@innocraft.com>

---------

Co-authored-by: Altamash Shaikh <altamash@innocraft.com>

Author: lachiebol

API.php

@@ -15,31 +15,32 @@
 use Piwik\Piwik;
 
 /**
- * Bandwidth API lets you request bandwidth metrics for page views and downloads.
+ * Exposes reporting API endpoints for aggregated bandwidth metrics.
  *
  * @method static \Piwik\Plugins\Bandwidth\API getInstance()
  */
 class API extends \Piwik\Plugin\API
 {
     /**
-     * Returns bandwidth metrics for the requested site, period, and segment.
+     * Returns aggregated bandwidth metrics for the requested site selection and archive period.
+     * Includes overall, pageview, and download totals, optionally limited to specific metric columns.
      *
      * @param int|string|int[] $idSite Website ID(s) to query.
      *                         - 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 '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|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 string|array|false $columns Optional metric columns to return. Accepts a comma-separated list,
-     *                                    an array of metric names, or false to return all available metrics.
-     * @return DataTable|DataTable\Map Bandwidth metrics with integer values.
+     * @param string|null|false $segment Custom segment to filter the report.
+     *                                   Example: "referrerName==example.com"
+     *                                   Supports AND (;) and OR (,) operators.
+     * @param string|array|false $columns Metric columns to return.
+     *                                    Accepts a comma-separated list, an array of metric names,
+     *                                    or false to return all available bandwidth metrics.
+     * @return DataTable|DataTable\Map A table containing the requested bandwidth metric totals as integers.
      */
     public function get($idSite, $period, $date, $segment = false, $columns = false)
     {

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## Changelog
 
+- 5.0.6 - 2026-04-27 - Updated API documentation
 - 5.0.5 - 2026-03-02 - Updated API documentation
 - 5.0.4 - 2025-10-27 - Updated screenshot for Marketplace
 - 5.0.3 - 2025-07-07 - Textual change

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "Bandwidth",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Monitor Bandwidth for each page, download, and measure overall traffic in bytes. For requirements check out the description.",
   "theme": false,
   "keywords": ["bandwidth", "filesize", "size", "download"],