darwin: Document OS-specific behaviour of libusb_cancel_transfer

The behaviour of libusb_cancel_transfer is different on Darwin:

- Cancellation cancels all transfers on the same endpoint.

- A ClearFeature(ENDPOINT_HALT) request is sent after cancellation.

This documents both differences and their implications.

Fixes #1110
Closes #1121

libusb/io.c

@@ -1576,6 +1576,26 @@ int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer)
  * \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED
  * "LIBUSB_TRANSFER_CANCELLED."
  *
+ * This function behaves differently on Darwin-based systems (macOS and iOS):
+ *
+ * - Calling this function for one transfer will cause all transfers on the
+ *   same endpoint to be cancelled. Your callback function will be invoked with
+ *   a transfer status of
+ *   \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED
+ *   "LIBUSB_TRANSFER_CANCELLED" for each transfer that was cancelled.
+
+ * - Calling this function also sends a \c ClearFeature(ENDPOINT_HALT) request
+ *   for the transfer's endpoint. If the device does not handle this request
+ *   correctly, the data toggle bits for the endpoint can be left out of sync
+ *   between host and device, which can have unpredictable results when the
+ *   next data is sent on the endpoint, including data being silently lost.
+ *   A call to \ref libusb_clear_halt will not resolve this situation, since
+ *   that function uses the same request. Therefore, if your program runs on
+ *   Darwin and uses a device that does not correctly implement
+ *   \c ClearFeature(ENDPOINT_HALT) requests, it may only be safe to cancel
+ *   transfers when followed by a device reset using
+ *   \ref libusb_reset_device.
+ *
  * \param transfer the transfer to cancel
  * \returns 0 on success
  * \returns LIBUSB_ERROR_NOT_FOUND if the transfer is not in progress,

libusb/version_nano.h

@@ -1 +1 @@
-#define LIBUSB_NANO 11722
+#define LIBUSB_NANO 11723