docs: enhance GraphQL schema documentation

- Added comprehensive descriptions to all types, interfaces, and fields in 'schema/api_commons.graphql'.

- Improved documentation for mutations and input/response types in 'schema/mutations.graphql'.

- Added detailed descriptions for all queries and their arguments in 'schema/queries.graphql'.

- Enhanced documentation for core Zabbix types and enums in 'schema/zabbix.graphql'.

- Updated extension schemas under 'schema/extensions/' with proper GraphQL descriptions.

- Verified schema validity via 'graphql-codegen' and ran all tests to ensure consistency.

schema/extensions/display_devices.graphql

@@ -16,60 +16,94 @@ type SinglePanelDevice implements Host & Device {
     state: PanelState
 }
 
+"""
+Represents the state of a single panel device.
+"""
 type PanelState implements DeviceState {
+    """Operational data (telemetry)."""
     operational: OperationalDeviceData
+    """Current display state."""
     current: PanelCurrentState
 }
 
+"""
+Represents the current state of a panel.
+"""
 type PanelCurrentState {
+    """The current values being displayed on the panel."""
     values: PanelValues
 }
 
+"""
+Specific values displayed on a panel.
+"""
 type PanelValues {
     """
-    Index of the bitmap which is displayed
+    Index of the bitmap which is displayed.
     """
     contentIndex: Int
     """
-    Hash of the bitmap which is displayed
+    Hash of the bitmap which is displayed.
     """
     contentKey: String
     """
-    Text representation of what is displayed
+    Text representation of what is displayed.
     """
     contentText: String
 }
 
 """
 The FourPanelDevice is a panel which allows to define pictures in 4
-subpanels, called TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT
+subpanels, called TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT.
 """
 type FourPanelDevice implements Host & Device {
+    """Internal Zabbix ID of the device."""
     hostid: ID!
     """
-    Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
+    Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
     """
     host: String!
+    """Classification of the device."""
     deviceType: String
+    """List of host groups this device belongs to."""
     hostgroups: [HostGroup!]
+    """Visible name of the device."""
     name: String
+    """Device configuration tags."""
     tags: DeviceConfig
+    """State of the four-panel device."""
     state: FourPanelState
 }
 
+"""
+Represents the state of a four-panel device.
+"""
 type FourPanelState implements DeviceState {
+    """Operational data (telemetry)."""
     operational: OperationalDeviceData
+    """Current state of all four panels."""
     current: FourPanelCurrentState
 }
 
+"""
+Represents the combined current state of four panels.
+"""
 type FourPanelCurrentState {
+    """The values for each of the four panels."""
     values: FourPanelValues
 }
 
+"""
+Values for each of the four panels in a FourPanelDevice.
+"""
 type FourPanelValues {
+    """State of the top-left panel."""
     TOP_LEFT: PanelValues
+    """State of the top-right panel."""
     TOP_RIGHT: PanelValues
+    """State of the bottom-left panel."""
     BOTTOM_LEFT: PanelValues
+    """State of the bottom-right panel."""
     BOTTOM_RIGHT: PanelValues
 }
 

schema/extensions/location_tracker_commons.graphql

@@ -27,6 +27,9 @@ type SensorDistanceValue implements DeviceValue {
     """
     time: String
 
+    """
+    Dummy field to allow for empty interfaces.
+    """
     _empty: String
 }
 
@@ -34,8 +37,11 @@ type SensorDistanceValue implements DeviceValue {
 Represents a coordinate in 3D space with x, y, and z components.
 """
 type Position {
+    """X coordinate."""
     x: Float
+    """Y coordinate."""
     y: Float
+    """Z coordinate."""
     z: Float
 }
 
@@ -43,7 +49,9 @@ type Position {
 Represents the result of a position calculation, including the calculated position and accuracy.
 """
 type PositionCalculatorResult {
+    """The calculated 3D position."""
     position: Position
+    """The estimated accuracy of the calculation."""
     accuracy: Float
 }
 
@@ -51,10 +59,16 @@ type PositionCalculatorResult {
 Concrete implementation of a DeviceValueMessage for sensor distance data.
 """
 type SensorDistanceMessage implements DeviceValueMessage {
+    """The unique identifier of the device."""
     deviceKey: String
+    """Timestamp of the message."""
     timestamp: String
+    """Name of the attribute."""
     attributeName: String
+    """Name of the topic."""
     topicName: String
+    """Type of the device."""
     deviceType: String
+    """The sensor distance value payload."""
     value: SensorDistanceValue
 }

schema/extensions/location_tracker_devices.graphql

@@ -1,45 +1,55 @@
 """
 DistanceTracker represents a device which can detect other devices around itself and estimate
 the distances, e.g. by using Bluetooth scanning technology and estimating the distance.
-
 """
 type DistanceTrackerDevice implements Host & Device {
+    """Internal Zabbix ID of the device."""
     hostid: ID!
     """
-    Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname
+    Per convention a uuid is used as hostname to identify devices if they do not have a unique hostname.
     """
     host: String!
+    """Classification of the device."""
     deviceType: String
+    """List of host groups this device belongs to."""
     hostgroups: [HostGroup!]
+    """Visible name of the device."""
     name: String
+    """Device configuration tags."""
     tags: DeviceConfig
+    """State of the distance tracker device."""
     state: DistanceTrackerState
 }
 
+"""
+Represents the state of a distance tracker device.
+"""
 type DistanceTrackerState implements DeviceState {
+    """Operational data (telemetry)."""
     operational: OperationalDeviceData
+    """Current business values (detected devices and distances)."""
     current: DistanceTrackerValues
 }
 
 """
-Aggregated information of devices detected around the tracker
+Aggregated information of devices detected around the tracker.
 """
 type DistanceTrackerValues {
     """
-    Start of time interval for the delivered device counting value
+    Start of time interval for the delivered device counting value.
     """
     timeFrom: Time
     """
-    End of time interval for the delivered device counting value
+    End of time interval for the delivered device counting value.
     """
     timeUntil: Time
 
     """
-    Number of unique deviceKeys detected between timeFrom and timeUnti
+    Number of unique device keys detected between timeFrom and timeUntil.
     """
     count: Int
     """
-    Detailed information about devices detected nearby
+    Detailed information about devices detected nearby.
     """
     distances: [SensorDistanceValue!]
 }