Document HIDAPI API usage contract for AI coding agents #834

Merged

Youw merged 1 commit from document-api-usage-contract into master

2026-08-14 06:16:09 -05:00

Youw commented

2026-08-14 05:34:03 -05:00

(Migrated from github.com)

Adds a "HIDAPI API usage contract" section to AGENTS.md documenting the library lifecycle (hid_init first, hid_exit last and only after all devices are closed, neither ever concurrent with anything else) and the multi-threading rules from the Multi‐threading Notes wiki page, which remains the authoritative reference.

It also states explicitly that a finding whose trigger requires violating that contract — e.g. calling hid_exit() while other threads still use the API, or unsynchronized concurrent first-time initialization — is application misuse rather than a library defect, and must not be reported as a bug or "fixed" by adding synchronization. The intent is to stop AI reviewers and agents from repeatedly raising contract-violating scenarios as defects, and to keep generated example/test code within the supported usage.

Related to: #788

Assisted-by: claude-code:claude-opus-5

Adds a "HIDAPI API usage contract" section to `AGENTS.md` documenting the library lifecycle (`hid_init` first, `hid_exit` last and only after all devices are closed, neither ever concurrent with anything else) and the multi-threading rules from the [Multi‐threading Notes](https://github.com/libusb/hidapi/wiki/Multi%E2%80%90threading-Notes) wiki page, which remains the authoritative reference. It also states explicitly that a finding whose trigger requires violating that contract — e.g. calling `hid_exit()` while other threads still use the API, or unsynchronized concurrent first-time initialization — is application misuse rather than a library defect, and must not be reported as a bug or "fixed" by adding synchronization. The intent is to stop AI reviewers and agents from repeatedly raising contract-violating scenarios as defects, and to keep generated example/test code within the supported usage. Related to: #788 Assisted-by: claude-code:claude-opus-5