Doc: update hotplug, topology and descriptor documentation

* Also fix some typos
* Closes #95

5 files changed, 36 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/descriptor.c b/libusb/descriptor.c
index ec5c344..ba6d146 100644
--- a/libusb/descriptor.c
+++ b/libusb/descriptor.c
@@ -541,6 +541,9 @@ int usbi_device_cache_descriptor(libusb_device *dev)
  *
  * This is a non-blocking function; the device descriptor is cached in memory.
  *
+ * Note since libusbx-1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, this
+ * function always succeeds.
+ *
  * \param dev the device
  * \param desc output location for the descriptor data
  * \returns 0 on success or a LIBUSB_ERROR code on failure
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