docs: Clear endpoint halt issued after cancellation only for macOS < 10.5

Also remove comment about possible endpoint halt, which seems not
correct, as discussed in issue #1110.

References #1110
Closes #1117

Signed-off-by: Tormod Volden <debian.tormod@gmail.com>

2 files changed, 18 insertions, 16 deletions

diff --git a/libusb/io.c b/libusb/io.c
index 2f38d67..e4753fc 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -311,11 +311,11 @@ if (r == 0 && actual_length == sizeof(data)) {
  * libusb_cancel_transfer() is asynchronous/non-blocking in itself. When the
  * cancellation actually completes, the transfer's callback function will
  * be invoked, and the callback function should check the transfer status to
- * determine that it was cancelled. On macOS and iOS it is not possible to
- * cancel a single transfer. In this case cancelling one tranfer on an endpoint
- * will cause all transfers on that endpoint to be cancelled. In some cases
- * the call may cause the endpoint to stall. A call to \ref libusb_clear_halt
- * may be needed.
+ * determine that it was cancelled.
+ *
+ * On macOS and iOS it is not possible to cancel a single transfer. In this
+ * case cancelling one transfer on an endpoint will cause all transfers on
+ * that endpoint to be cancelled.
  *
  * Freeing the transfer after it has been cancelled but before cancellation
  * has completed will result in undefined behaviour.
@@ -1588,16 +1588,18 @@ int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer)
  *   \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
+ * - When built for macOS versions prior to 10.5, this function sends a
+ *   \c ClearFeature(ENDPOINT_HALT) request for the transfer's endpoint.
+ *   (Prior to libusb 1.0.27, this request was sent on all Darwin systems.)
+ *   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
+ *   macOS < 10.5 (or libusb < 1.0.27), 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
diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index 99985a0..f30d8ef 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 11756
+#define LIBUSB_NANO 11757