Updates

Author: 27pchrisl

src/Interfaces/Hardware/Device.php

@@ -4,13 +4,45 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Device
+ *
+ * Defines the basic contract for a hardware device, allowing it to be opened, closed,
+ * and support reading and writing data.
+ */
 interface Device
 {
+    /**
+     * Open a connection to the device specified by its pathname.
+     *
+     * @param  string  $pathname  The device file or resource path.
+     * @param  int  $flags  Flags to control how the device is opened.
+     * @return int Returns a resource handle or file descriptor on success, or -1 on failure.
+     */
     public function open(string $pathname, int $flags): int;
 
+    /**
+     * Close the connection to the device.
+     *
+     * @return int Returns 0 on success or -1 on failure.
+     */
     public function close(): int;
 
+    /**
+     * Read from the device into the provided buffer.
+     *
+     * @param  string  $buffer  Variable to store the read data (passed by reference).
+     * @param  int  $count  Maximum number of bytes to read.
+     * @return int The number of bytes read, or -1 on error.
+     */
     public function read(string &$buffer, int $count): int;
 
+    /**
+     * Write data to the device.
+     *
+     * @param  string  $buffer  The data to write.
+     * @param  int  $count  Number of bytes to write.
+     * @return int The number of bytes written, or -1 on error.
+     */
     public function write(string $buffer, int $count): int;
 }

src/Interfaces/Hardware/Ioctl.php

@@ -4,7 +4,19 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Ioctl
+ *
+ * Hardware abstraction for devices supporting ioctl operations.
+ */
 interface Ioctl
 {
+    /**
+     * Perform an ioctl operation on the device.
+     *
+     * @param  int  $request  The ioctl request code.
+     * @param  string|null  $argp  Optional; additional argument for the ioctl operation, passed by reference.
+     * @return int The result code from the ioctl system call.
+     */
     public function ioctl(int $request, ?string &$argp = null): int;
 }

src/Interfaces/Hardware/IoctlCommand.php

@@ -4,4 +4,9 @@
 
 use BackedEnum;
 
+/**
+ * Interface IoctlCommand
+ *
+ * Represents an IOCTL (input/output control) command.
+ */
 interface IoctlCommand extends BackedEnum {}

src/Interfaces/Hardware/PiControl.php

@@ -4,4 +4,14 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface PiControl
+ *
+ * Represents a PiControl hardware component, combining device operations,
+ * IOCTL (input/output control), and seek capabilities.
+ *
+ * @see Device
+ * @see Ioctl
+ * @see Seek
+ */
 interface PiControl extends Device, Ioctl, Seek {}

src/Interfaces/Hardware/Seek.php

@@ -4,7 +4,22 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Seek
+ *
+ * Provides an interface for seeking within a hardware context, such as moving a file pointer
+ * or device resource to a specific position.
+ */
 interface Seek
 {
+    /**
+     * Set the position of the resource pointer.
+     *
+     * Moves the pointer to a specific offset, relative to the position defined by $whence.
+     *
+     * @param  int  $offset  The position to move to, measured in bytes.
+     * @param  int  $whence  The reference position for the offset; one of SEEK_SET, SEEK_CUR, or SEEK_END.
+     * @return int The new position of the pointer on success.
+     */
     public function lseek(int $offset, int $whence): int;
 }

src/Interfaces/Hardware/Stream.php

@@ -4,8 +4,17 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Stream
+ *
+ * Represents a hardware stream that can provide a file descriptor resource.
+ */
 interface Stream
 {
-    /** @return resource */
+    /**
+     * Open or retrieve a file descriptor resource for the stream.
+     *
+     * @return resource The file descriptor resource associated with the stream.
+     */
     public function fdopen(): mixed;
 }

src/Interfaces/Hardware/Struct.php

@@ -4,11 +4,31 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Struct
+ *
+ * Interface for packable and unpackable binary structure representations.
+ */
 interface Struct
 {
+    /**
+     * Packs the current data structure into a binary string.
+     *
+     * @return string The packed binary representation of this structure.
+     */
     public function pack(): string;
 
+    /**
+     * Unpacks the given binary buffer into this data structure.
+     *
+     * @param  string  $buffer  The binary buffer to unpack into this structure.
+     */
     public function unpack(string $buffer): void;
 
+    /**
+     * Returns the length in bytes of the packed data structure.
+     *
+     * @return int The length in bytes.
+     */
     public function length(): int;
 }

src/Interfaces/Hardware/Terminal.php

@@ -4,19 +4,68 @@
 
 namespace Flat3\RevPi\Interfaces\Hardware;
 
+/**
+ * Interface Terminal
+ *
+ * Represents terminal communication capabilities common to hardware serial interfaces.
+ * Extends Device, Ioctl, and Stream interfaces.
+ */
 interface Terminal extends Device, Ioctl, Stream
 {
+    /**
+     * Get the input baud rate stored in the termios buffer.
+     *
+     * @param  string  &$buffer  The termios structure buffer (passed by reference).
+     * @return int The input baud rate, or -1 on failure.
+     */
     public function cfgetispeed(string &$buffer): int;
 
+    /**
+     * Get the output baud rate stored in the termios buffer.
+     *
+     * @param  string  &$buffer  The termios structure buffer (passed by reference).
+     * @return int The output baud rate, or -1 on failure.
+     */
     public function cfgetospeed(string &$buffer): int;
 
+    /**
+     * Set the input baud rate in the termios buffer.
+     *
+     * @param  string  &$buffer  The termios structure buffer (passed by reference).
+     * @param  int  $speed  The new input baud rate to set.
+     * @return int Returns 0 on success, -1 on failure.
+     */
     public function cfsetispeed(string &$buffer, int $speed): int;
 
+    /**
+     * Set the output baud rate in the termios buffer.
+     *
+     * @param  string  &$buffer  The termios structure buffer (passed by reference).
+     * @param  int  $speed  The new output baud rate to set.
+     * @return int Returns 0 on success, -1 on failure.
+     */
     public function cfsetospeed(string &$buffer, int $speed): int;
 
+    /**
+     * Discard data in the input/output queue.
+     *
+     * @param  int  $queue_selector  Selector indicating which queue(s) to flush (e.g., TCIFLUSH, TCOFLUSH).
+     * @return int Returns 0 on success, or -1 on failure.
+     */
     public function tcflush(int $queue_selector): int;
 
+    /**
+     * Wait until all output written to the terminal is transmitted.
+     *
+     * @return int Returns 0 on success, or -1 on failure.
+     */
     public function tcdrain(): int;
 
+    /**
+     * Transmit a continuous stream of zero bits for a specific duration.
+     *
+     * @param  int  $duration  Duration to send the break (in 0.25s units), default is 0 for 0.25 seconds.
+     * @return int Returns 0 on success, or -1 on failure.
+     */
     public function tcsendbreak(int $duration = 0): int;
 }

src/Interfaces/Led.php

@@ -8,9 +8,22 @@
 
 interface Led
 {
+    /**
+     * Set the LED to the specified colour.
+     *
+     * @param  LedColour  $colour  The colour to set the LED.
+     */
     public function set(LedColour $colour): void;
 
+    /**
+     * Get the current colour of the LED.
+     *
+     * @return LedColour The current colour of the LED.
+     */
     public function get(): LedColour;
 
+    /**
+     * Turn off the LED.
+     */
     public function off(): void;
 }

src/Interfaces/Module.php

@@ -7,15 +7,46 @@
 use Flat3\RevPi\Led\LedPosition;
 use Flat3\RevPi\Monitors\Monitor;
 
+/**
+ * Interface Module
+ *
+ * Represents a hardware module in the RevPi ecosystem, providing methods for controlling
+ * LEDs, accessing process images, monitoring, and serial port access.
+ */
 interface Module
 {
+    /**
+     * Get a LED instance at the specified position.
+     *
+     * @param  LedPosition  $position  The position of the LED to retrieve.
+     * @return Led The LED instance at the specified position.
+     */
     public function getLed(LedPosition $position): Led;
 
+    /**
+     * Obtain the process image associated with this module.
+     *
+     * @return ProcessImage The process image of the module.
+     */
     public function getProcessImage(): ProcessImage;
 
+    /**
+     * Resume normal operation for the module after a pause or reset.
+     */
     public function resume(): void;
 
+    /**
+     * Attach a monitor to the module for status tracking or event watching.
+     *
+     * @param  Monitor  $monitor  The monitor instance to attach.
+     */
     public function monitor(Monitor $monitor): void;
 
+    /**
+     * Get a serial port instance for communication on the specified device path.
+     *
+     * @param  string  $devicePath  The path to the serial device (e.g. "/dev/ttyS0").
+     * @return SerialPort The serial port instance.
+     */
     public function getSerialPort(string $devicePath): SerialPort;
 }