If I don't do it today, it'll never happen, so here goes for review.
Regards,
/Pete
>From ba07137acc2123178fed38625c676bb0a478e065 Mon Sep 17 00:00:00 2001
From: Pete Batard <p...@akeo.ie>
Date: Wed, 3 Jul 2013 22:41:55 +0100
Subject: [PATCH] Doc: update hotplug and topology documentation
* Also fix some typos
* Closes #95
---
libusb/core.c | 21 +++++++++++++++------
libusb/hotplug.c | 20 ++++++++++++++------
libusb/libusb.h | 6 +++---
libusb/version_nano.h | 2 +-
4 files changed, 33 insertions(+), 16 deletions(-)
diff --git a/libusb/core.c b/libusb/core.c
index 0795597..e29e8df 100644
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -97,7 +97,7 @@ struct list_head active_contexts_list;
* usually won't need to thread)
* - Lightweight with lean API
* - Compatible with libusb-0.1 through the libusb-compat-0.1 translation layer
- * - Hotplug support (see \ref hotplug)
+ * - Hotplug support (on some platforms). See \ref hotplug.
*
* \section gettingstarted Getting Started
*
@@ -737,7 +737,16 @@ uint8_t API_EXPORTED libusb_get_bus_number(libusb_device
*dev)
}
/** \ingroup dev
- * Get the number of the port that a device is connected to
+ * Get the number of the port that a device is connected to.
+ * Unless the OS does something funky, or you are hot-plugging USB extension
cards,
+ * the port number returned by this call is usually guaranteed to be uniquely
tied
+ * to a physical port, meaning that different devices plugged on the same
physical
+ * port should return the same port number.
+ *
+ * But outside of this, there is no guarantee that the port number returned by
this
+ * call will remain the same, or even match the order in which ports have been
+ * numbered by the HUB/HCD manufacturer.
+ *
* \param dev a device
* \returns the port number (0 if not available)
*/
@@ -792,12 +801,12 @@ int API_EXPORTED libusb_get_port_path(libusb_context
*ctx, libusb_device *dev,
}
/** \ingroup dev
- * Get the the parent from the specified device [EXPERIMENTAL]
+ * Get the the parent from the specified device.
* \param dev a device
* \returns the device parent or NULL if not available
- * You should issue a libusb_get_device_list() before calling this
+ * You should issue a \ref libusb_get_device_list() before calling this
* function and make sure that you only access the parent before issuing
- * libusb_free_device_list(). The reason is that libusbx currently does
+ * \ref libusb_free_device_list(). The reason is that libusbx currently does
* not maintain a permanent list of device instances, and therefore can
* only guarantee that parents are fully instantiated within a
* libusb_get_device_list() - libusb_free_device_list() block.
@@ -897,7 +906,7 @@ int API_EXPORTED libusb_get_max_packet_size(libusb_device
*dev,
* Calculate the maximum packet size which a specific endpoint is capable is
* sending or receiving in the duration of 1 microframe
*
- * Only the active configution is examined. The calculation is based on the
+ * Only the active configuration is examined. The calculation is based on the
* wMaxPacketSize field in the endpoint descriptor as described in section
* 9.6.6 in the USB 2.0 specifications.
*
diff --git a/libusb/hotplug.c b/libusb/hotplug.c
index 77ccb31..4bc4cbd 100644
--- a/libusb/hotplug.c
+++ b/libusb/hotplug.c
@@ -35,25 +35,33 @@
/**
* @defgroup hotplug Device hotplug event notification
- * This page details how to use the libusb hotplug interface.
+ * This page details how to use the libusb hotplug interface, where available.
+ *
+ * Be mindful that not all platforms currently implement hotplug notification
and
+ * that you should first call on \ref libusb_has_capability() with parameter
+ * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.
*
* \page hotplug Device hotplug event notification
*
* \section intro Introduction
*
* Version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, has added support
- * for hotplug events. This interface allows you to request notification for
- * the arrival and departure of matching USB devices.
+ * for hotplug events on <b>some</b> platforms (you should test if your
platform
+ * supports hotplug notification by calling \ref libusb_has_capability() with
+ * parameter \ref LIBUSB_CAP_HAS_HOTPLUG).
+ *
+ * This interface allows you to request notification for the arrival and
departure
+ * of matching USB devices.
*
* To receive hotplug notification you register a callback by calling
- * libusb_hotplug_register_callback(). This function will optionally return
- * a handle that can be passed to libusb_hotplug_deregister_callback().
+ * \ref libusb_hotplug_register_callback(). This function will optionally
return
+ * a handle that can be passed to \ref libusb_hotplug_deregister_callback().
*
* A callback function must return an int (0 or 1) indicating whether the
callback is
* expecting additional events. Returning 0 will rearm the callback and 1 will
cause
* the callback to be deregistered.
*
- * Callbacks for a particulat context are automatically deregistered by
libusb_exit().
+ * Callbacks for a particular context are automatically deregistered by
libusb_exit().
*
* As of 1.0.16 there are two supported hotplug events:
* - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready
to use
diff --git a/libusb/libusb.h b/libusb/libusb.h
index 5e1c23c..e8e1201 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -1260,14 +1260,14 @@ struct libusb_transfer {
};
/** \ingroup misc
- * Capabilities supported by this instance of libusb. Test if the loaded
- * library supports a given capability by calling
+ * Capabilities supported by an instance of libusb on the current running
+ * platform. Test if the loaded library supports a given capability by calling
* \ref libusb_has_capability().
*/
enum libusb_capability {
/** The libusb_has_capability() API is available. */
LIBUSB_CAP_HAS_CAPABILITY = 0x0000,
- /** Hotplug support is available. */
+ /** Hotplug support is available on this platform. */
LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
/** The library can access HID devices without requiring user
intervention.
* Note that before being able to actually access an HID device, you may
diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index cfcd51f..88625ac 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 10767
+#define LIBUSB_NANO 10768
--
1.8.0.msysgit.0
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
libusbx-devel mailing list
libusbx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/libusbx-devel
