From 0c88090175e1dec35cb081daf6e1a89bccfc0def Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Sun, 23 Aug 2026 17:26:28 -0500 Subject: [PATCH] document DeviceInfo Add container level documentation and doc comments for the fields and init, in the same style as the comments Device carries. The container comment records what the struct actually is, a snapshot of one HIDIOCGRAWINFO ioctl paired with the device it was read from, and where to get one. The ownership rule is the part that was only discoverable from the source: the embedded Device stays open and belongs to whoever opened it, so callers of getDeviceInfo and DeviceInfoIterator still have to close it. The bustype comment repeats the warning from getBusType that ioctl.BUS is non-exhaustive, and init notes that info is not referenced after it returns and that Device.getDeviceInfo is the usual way in. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JRS7gtG7BeWuwFUf8xW4qS --- src/DeviceInfo.zig | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/src/DeviceInfo.zig b/src/DeviceInfo.zig index f1843df..43a33f2 100644 --- a/src/DeviceInfo.zig +++ b/src/DeviceInfo.zig @@ -1,6 +1,18 @@ // SPDX-FileCopyrightText: © 2024 Jeffrey C. Ollie // SPDX-License-Identifier: MIT +//! Identifying information for a `hidraw` device: the bus it is attached to, +//! its vendor ID and its product ID, as reported by a single `HIDIOCGRAWINFO` +//! ioctl. +//! +//! A `DeviceInfo` also carries the open `Device` it was read from, so that +//! code enumerating devices can pick the one it wants and keep using it +//! without reopening. The device is not owned by the `DeviceInfo`; whoever +//! opened it still has to `close` it. +//! +//! Obtain one with `Device.getDeviceInfo`, or by iterating with +//! `DeviceInfoIterator`. + const DeviceInfo = @This(); const std = @import("std"); @@ -12,18 +24,28 @@ const ioctl = @import("ioctl.zig"); const Device = @import("Device.zig"); -/// The hidraw device. +/// The open `hidraw` device this information was read from. +/// +/// Still owned by whoever opened it, and still has to be closed. device: Device, -/// The bus type. +/// The bus the device is attached to. +/// +/// `ioctl.BUS` is non-exhaustive, because the kernel may report a bus this +/// library does not name yet. bustype: ioctl.BUS, -/// The vendor ID. +/// The vendor ID (VID). vendor: u16, -/// The product ID. +/// The product ID (PID). product: u16, +/// Pair `device` with the `hidraw_devinfo` just read from it. +/// +/// `info` is only read from, and is not referenced after this returns. +/// Callers normally go through `Device.getDeviceInfo` instead of calling +/// this directly. pub fn init(device: Device, info: *const ioctl.hidraw_devinfo) DeviceInfo { return .{ .device = device, -- knotmirror 0.0.1