Create more documentation (#7627)

* Documentation, format class, no modification.

app/system/resources/classes/bsd_system_information.php

@@ -31,6 +31,11 @@
  */
 class bsd_system_information extends system_information {
 
+	/**
+	 * Returns the number of CPU cores available on the system.
+	 *
+	 * @return int The number of CPU cores.
+	 */
 	public function get_cpu_cores(): int {
 		$result = shell_exec("dmesg | grep -i --max-count 1 CPUs | sed 's/[^0-9]*//g'");
 		$cpu_cores = trim($result);
@@ -38,6 +43,12 @@ class bsd_system_information extends system_information {
 	}
 
 	//get the CPU details
+
+	/**
+	 * Returns the current CPU usage percentage.
+	 *
+	 * @return float The current CPU usage percentage.
+	 */
 	public function get_cpu_percent(): float {
 		$result = shell_exec('ps -A -o pcpu');
 		$percent_cpu = 0;
@@ -49,10 +60,20 @@ class bsd_system_information extends system_information {
 		return $percent_cpu;
 	}
 
+	/**
+	 * Returns the system uptime in seconds.
+	 *
+	 * @return string The system uptime in seconds.
+	 */
 	public function get_uptime() {
 		return shell_exec('uptime');
 	}
 
+	/**
+	 * Returns the current CPU usage percentage per core.
+	 *
+	 * @return array An associative array where keys are core indices and values are their respective CPU usage percentages.
+	 */
 	public function get_cpu_percent_per_core(): array {
 		static $last = [];
 		$results = [];
@@ -94,11 +115,11 @@ class bsd_system_information extends system_information {
 	}
 
 	/**
+	 * Returns the current network speed for a given interface.
 	 *
-	 * @staticvar array $last
-	 * @param string $interface
-	 * @return array
-	 * @depends FreeBSD Version 12
+	 * @param string $interface The network interface to query (default: 'em0')
+	 *
+	 * @return array An array containing the current receive and transmit speeds in bytes per second.
 	 */
 	public function get_network_speed(string $interface = 'em0'): array {
 		static $last = [];

app/system/resources/classes/linux_system_information.php

@@ -31,6 +31,13 @@
  */
 class linux_system_information extends system_information {
 
+	/**
+	 * Returns the number of CPU cores available on the system.
+	 *
+	 * This method executes a shell command to parse the /proc/cpuinfo file and counts the number of processor entries found.
+	 *
+	 * @return int The total number of CPU cores
+	 */
 	public function get_cpu_cores(): int {
 		$result = @trim(shell_exec("grep -P '^processor' /proc/cpuinfo"));
 		$cpu_cores = count(explode("\n", $result));
@@ -38,6 +45,16 @@ class linux_system_information extends system_information {
 	}
 
 	//get the CPU details
+
+	/**
+	 * Returns the current CPU usage as a percentage.
+	 *
+	 * This method reads the CPU statistics from /proc/stat and calculates
+	 * the CPU usage by comparing the total and idle time of each core.
+	 * The result is rounded to two decimal places.
+	 *
+	 * @return float The current CPU usage in percent.
+	 */
 	public function get_cpu_percent(): float {
 		$stat1 = file_get_contents('/proc/stat');
 		usleep(500000);
@@ -73,10 +90,27 @@ class linux_system_information extends system_information {
 		return round($percent_cpu / $core_count, 2);
 	}
 
+	/**
+	 * Returns the current system uptime as reported by the 'uptime' command.
+	 *
+	 * This method executes the 'uptime' command and returns its output.
+	 *
+	 * @return string The current system uptime.
+	 */
 	public function get_uptime() {
 		return shell_exec('uptime');
 	}
 
+	/**
+	 * Returns the current CPU usage as a percentage per core.
+	 *
+	 * This method reads the CPU statistics from /proc/stat and calculates
+	 * the CPU usage by comparing the total and idle time of each core.
+	 * The result is rounded to two decimal places.
+	 *
+	 * @return array An array where the keys are the core numbers (starting at 0)
+	 *               and the values are the current CPU usage for each core in percent.
+	 */
 	public function get_cpu_percent_per_core(): array {
 		static $last = [];
 
@@ -107,6 +141,16 @@ class linux_system_information extends system_information {
 		return $results;
 	}
 
+	/**
+	 * Returns the current network speed for the specified interface.
+	 *
+	 * This method reads the network statistics from /proc/net/dev and calculates
+	 * the network speed by comparing the received and transmitted bytes between two measurements.
+	 *
+	 * @param string $interface The network interface to read stats from. Defaults to 'eth0'.
+	 *
+	 * @return array An array containing the current receive (rx_bps) and transmit (tx_bps) speeds in bits per second.
+	 */
 	public function get_network_speed(string $interface = 'eth0'): array {
 		static $last = [];
 

app/system/resources/classes/session.php

@@ -35,7 +35,9 @@ class session {
 
 	/**
 	 * Removes old php session files. Called by the maintenance application.
+	 *
 	 * @param settings $settings A settings object
+	 *
 	 * @return void
 	 */
 	public static function filesystem_maintenance(settings $settings): void {

app/system/resources/classes/system_dashboard_service.php

@@ -38,6 +38,11 @@ class system_dashboard_service extends base_websocket_system_service {
 	private $network_status_refresh_interval;
 	private $network_interface;
 
+	/**
+	 * Reloads settings from database, config file and websocket server.
+	 *
+	 * @return void
+	 */
 	protected function reload_settings(): void {
 		static::set_system_information();
 
@@ -64,8 +69,12 @@ class system_dashboard_service extends base_websocket_system_service {
 	}
 
 	/**
-	 * Executes once
-	 * @return void
+	 * Registers topics for broadcasting system information.
+	 *
+	 * This method is responsible for setting up the system information object,
+	 * registering callback functions for cpu and network status requests, and
+	 * configuring timer callbacks to refresh these statuses at regular intervals.
+	 * It is only called once during initial startup.
 	 */
 	protected function register_topics(): void {
 
@@ -90,6 +99,17 @@ class system_dashboard_service extends base_websocket_system_service {
 		$this->info("Broadcasting Network Status every {$this->network_status_refresh_interval}s");
 	}
 
+	/**
+	 * Handles the network status request.
+	 *
+	 * This method retrieves the current network interface and speeds, constructs a response message,
+	 * logs the request for debugging purposes, and attempts to send the broadcast. If the Websocket server
+	 * is disconnected, it waits until reconnection before attempting to send again.
+	 *
+	 * @param string|null $message The original message that triggered this response (optional).
+	 *
+	 * @return int The refresh interval for network status in seconds.
+	 */
 	public function on_network_status($message = null): int {
 		// Get RX (receive) and TX (transmit) bps
 		$network_rates = self::$system_information->get_network_speed($this->network_interface);
@@ -134,6 +154,15 @@ class system_dashboard_service extends base_websocket_system_service {
 		return $this->network_status_refresh_interval;
 	}
 
+	/**
+	 * Handles the selection of a network interface from a message.
+	 *
+	 * This method checks if the message is an instance of WebSocketMessage and if it contains
+	 * a 'network_interface' payload. If both conditions are true, it sets the network interface
+	 * property to the value of the payload.
+	 *
+	 * @param websocket_message|null $message The message containing the selected network interface.
+	 */
 	public function on_network_interface_select($message = null): void {
 		if ($message !== null && $message instanceof websocket_message) {
 			$payload = $message->payload();
@@ -143,6 +172,17 @@ class system_dashboard_service extends base_websocket_system_service {
 		}
 	}
 
+	/**
+	 * Handles cpu status requests.
+	 *
+	 * This method is called to respond to incoming requests for the current CPU usage,
+	 * both total and per-core. It prepares a response message with the requested data
+	 * and sends it to all connected clients.
+	 *
+	 * @param null|websocket_message $message The request message, if responding to a specific request.
+	 *
+	 * @return int The interval at which this method should be called again to refresh the cpu status.
+	 */
 	public function on_cpu_status($message = null): int {
 		// Get total and per-core CPU usage
 		$cpu_percent_total = self::$system_information->get_cpu_percent();
@@ -192,10 +232,27 @@ class system_dashboard_service extends base_websocket_system_service {
 		return $this->cpu_status_refresh_interval;
 	}
 
+	/**
+	 * Returns the service name for system information.
+	 *
+	 * This method provides a unique identifier for the dashboard system information service.
+	 *
+	 * @return string The service name as a string, in this case "dashboard.system.information".
+	 */
 	public static function get_service_name(): string {
 		return "dashboard.system.information";
 	}
 
+	/**
+	 * Creates a filter chain for broadcasting system information.
+	 *
+	 * This method generates a filter based on the subscriber's permissions,
+	 * allowing them to receive only relevant system view information.
+	 *
+	 * @param subscriber $subscriber The subscriber object with permission data.
+	 *
+	 * @return ?filter A filter chain that matches the subscriber's permissions, or null if no match is found.
+	 */
 	public static function create_filter_chain_for(subscriber $subscriber): ?filter {
 		// Get the subscriber permissions
 		$permissions = $subscriber->get_permissions();
@@ -216,6 +273,15 @@ class system_dashboard_service extends base_websocket_system_service {
 		return $filter;
 	}
 
+	/**
+	 * Sets the system information object.
+	 *
+	 * This method creates a new instance of `SystemInformation` and stores it in
+	 * the class's static property `$system_information`. It is typically called once
+	 * during initial startup to establish the system information source.
+	 *
+	 * @return void
+	 */
 	public static function set_system_information(): void {
 		self::$system_information = system_information::new();
 	}

app/system/resources/classes/system_information.php

@@ -37,10 +37,20 @@ abstract class system_information {
 	abstract public function get_cpu_percent_per_core(): array;
 	abstract public function get_network_speed(string $interface = 'eth0'): array;
 
+	/**
+	 * Returns the system load average.
+	 *
+	 * @return array Three most recent one-minute load averages.
+	 */
 	public function get_load_average() {
 		return sys_getloadavg();
 	}
 
+	/**
+	 * Returns a system information object based on the underlying operating system.
+	 *
+	 * @return ?system_information The system information object for the current OS, or null if not supported.
+	 */
 	public static function new(): ?system_information {
 		if (stristr(PHP_OS, 'BSD')) {
 			return new bsd_system_information();

app/system/resources/dashboard/system_services.php

@@ -38,6 +38,13 @@
 
 //function to parse a FusionPBX service from a .service file
 	if (!function_exists('get_classname')) {
+		/**
+		 * Retrieves the name of a PHP class from an ExecStart directive in a service file.
+		 *
+		 * @param string $file Path to the service file.
+		 *
+		 * @return string The name of the PHP class, or empty string if not found.
+		 */
 		function get_classname(string $file) {
 			if (!file_exists($file)) {
 				return '';
@@ -55,6 +62,14 @@
 
 //function to check for running process: returns [running, pid, etime]
 	if (!function_exists('is_running')) {
+		/**
+		 * Checks if a process with the given name is currently running.
+		 *
+		 * @param string $name The name of the process to check for.
+		 *
+		 * @return array An array containing information about the process's status,
+		 *               including whether it's running, its PID, and how long it's been running.
+		 */
 		function is_running(string $name) {
 			$name = escapeshellarg($name);
 			$pid = trim(shell_exec("ps -aux | grep $name | grep -v grep | awk '{print \$2}' | head -n 1") ?? '');
@@ -68,6 +83,21 @@
 
 //function to format etime into friendly display
 	if (!function_exists('format_etime')) {
+		/**
+		 * Formats a time duration string into a human-readable format.
+		 *
+		 * The input string can be in one of the following formats:
+		 * - dd-hh:mm:ss
+		 * - hh:mm:ss
+		 * - mm:ss
+		 * - seconds (no units)
+		 *
+		 * If the input string is empty or invalid, an empty string will be returned.
+		 *
+		 * @param string $etime Time duration string to format.
+		 *
+		 * @return string Formatted time duration string in human-readable format.
+		 */
 		function format_etime($etime) {
 			// Format: [[dd-]hh:]mm:ss
 			if (empty($etime)) return '-';

app/system/resources/functions/system_information.php

@@ -83,6 +83,14 @@
 	//
 
 //system information
+	/**
+	 * Retrieves system information.
+	 *
+	 * @return array An array containing various system information such as PHP and switch versions,
+	 *               git repository details, operating system name, version, uptime, kernel, and type,
+	 *               memory usage, CPU usage, and disk space. The keys of the returned array are
+	 *               'version', 'git', 'path', 'switch', 'php', 'os', 'mem', and 'cpu'.
+	 */
 	function system_information(): array {
 		global $database, $db_type;
 		$system_information = [];