[roomplanner] Add some phpdoc

1 files changed, 17 insertions, 1 deletions

diff --git a/modules-available/roomplanner/page.inc.php b/modules-available/roomplanner/page.inc.php
index 3286b71a..13344322 100644
--- a/modules-available/roomplanner/page.inc.php
+++ b/modules-available/roomplanner/page.inc.php
@@ -74,6 +74,10 @@ class Page_Roomplanner extends Page
 		}
 	}
 
+	/**
+	 * Prepares required JSON data for editing a room's layout and sends
+	 * the resulting HTML skeleton plus JSON data to the browser.
+	 */
 	private function showLeafEditor(): void
 	{
 		$config = Database::queryFirst('SELECT roomplan, managerip, tutoruuid
@@ -117,6 +121,11 @@ class Page_Roomplanner extends Page
 		Render::addTemplate('footer', $params);
 	}
 
+	/**
+	 * Shows the simple editor for editing a non-leaf room in the tree structure of locations. This editor will
+	 * only allow you to set the relative location of the rooms to each other: stacked horizontally, or stacked
+	 * vertically. This is intended for rooms that can be joined via a removable wall.
+	 */
 	private function showComposedEditor(): void
 	{
 		// Load settings
@@ -365,7 +374,9 @@ class Page_Roomplanner extends Page
 	}
 
 	/**
-	 * @return array{computers: array}
+	 * Get all machines that are currently placed in the room to be edited. Returns a list of machines
+	 * with metadata like their position in the room, ip/hostname, etc.
+	 * @return array{computers: array<array{muuid: string, ip: string, mac_address: string, hostname: string, gridRow: int, gridCol: int, itemlook: string, istutor: bool}>}
 	 */
 	protected function getMachinesOnPlan(?string $tutorUuid): array
 	{
@@ -401,6 +412,11 @@ class Page_Roomplanner extends Page
 		return ['computers' => $machines];
 	}
 
+	/**
+	 * Returns a list of machines that potentially belong to the room/location currently
+	 * being edited.
+	 * @return array<array{machineuuid: string, macaddr: string, clientip: string, hostname: string, otherroom: string, fixedlocationid: ?int}>
+	 */
 	protected function getPotentialMachines(): array
 	{
 		$result = Database::simpleQuery('SELECT m.machineuuid, m.macaddr, m.clientip, m.hostname, l.locationname AS otherroom, m.fixedlocationid