docs: Prefer use of libusb_init_context() over old libusb_init()

- Replace some uses of the soft-deprecated libusb_init() and
  libusb_set_debug() with their updates.

- Updated various comments to favour use of the new functions.

- Notably remove \deprecated doxygen statement, since it causes
  -Wdocumentation compiler warnings.

- Notably update the xusb example to pass debug options to
  libusb_init_context() instead of setting environment variable.

- Also improve comments related to LIBUSB_API_VERSION and
  LIBUSBX_API_VERSION.

Closes #1408

[Tormod: Fix Doxygen formatting and references]
Signed-off-by: Tormod Volden <debian.tormod@gmail.com>

8 files changed, 66 insertions, 43 deletions

diff --git a/examples/xusb.c b/examples/xusb.c
index 441af01..239450c 100644
--- a/examples/xusb.c
+++ b/examples/xusb.c
@@ -1035,7 +1035,6 @@ static int test_device(uint16_t vid, uint16_t pid)
 
 int main(int argc, char** argv)
 {
-	static char debug_env_str[] = "LIBUSB_DEBUG=4";	// LIBUSB_LOG_LEVEL_DEBUG
 	bool show_help = false;
 	bool debug_mode = false;
 	const struct libusb_version* version;
@@ -1159,17 +1158,17 @@ int main(int argc, char** argv)
 		return 0;
 	}
 
-	// xusb is commonly used as a debug tool, so it's convenient to have debug output during libusb_init(),
-	// but since we can't call on libusb_set_option() before libusb_init(), we use the env variable method
-	old_dbg_str = getenv("LIBUSB_DEBUG");
+	version = libusb_get_version();
+	printf("Using libusb v%d.%d.%d.%d\n\n", version->major, version->minor, version->micro, version->nano);
+
+	// xusb is commonly used as a debug tool, so it's convenient to have debug output during libusb_init_context().
 	if (debug_mode) {
-		if (putenv(debug_env_str) != 0)
-			printf("Unable to set debug level\n");
+		const struct libusb_init_option options = {.option = LIBUSB_OPTION_LOG_LEVEL, .value = {.ival = LIBUSB_LOG_LEVEL_DEBUG}};
+		r = libusb_init_context(/*ctx=*/NULL, /*options=*/&options, /*num_options=*/1);
+	} else {
+		r = libusb_init_context(/*ctx=*/NULL, /*options=*/NULL, /*num_options=*/0);
 	}
 
-	version = libusb_get_version();
-	printf("Using libusb v%d.%d.%d.%d\n\n", version->major, version->minor, version->micro, version->nano);
-	r = libusb_init_context(/*ctx=*/NULL, /*options=*/NULL, /*num_options=*/0);
 	if (r < 0)
 		return r;
 
diff --git a/libusb/core.c b/libusb/core.c
index 2a715bf..0ea3b89 100644
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -336,18 +336,18 @@ if (cfg != desired)
  * libusb after one of them calls libusb_exit(), etc.
  *
  * This is made possible through libusb's <em>context</em> concept. When you
- * call libusb_init(), you are (optionally) given a context. You can then pass
+ * call libusb_init_context(), you are (optionally) given a context. You can then pass
  * this context pointer back into future libusb functions.
  *
  * In order to keep things simple for more simplistic applications, it is
  * legal to pass NULL to all functions requiring a context pointer (as long as
  * you're sure no other code will attempt to use libusb from the same process).
  * When you pass NULL, the default context will be used. The default context
- * is created the first time a process calls libusb_init() when no other
+ * is created the first time a process calls libusb_init_context() when no other
  * context is alive. Contexts are destroyed during libusb_exit().
  *
  * The default context is reference-counted and can be shared. That means that
- * if libusb_init(NULL) is called twice within the same process, the two
+ * if libusb_init_context(NULL, x, y) is called twice within the same process, the two
  * users end up sharing the same context. The deinitialization and freeing of
  * the default context will only happen when the last user calls libusb_exit().
  * In other words, the default context is created and initialized when its
@@ -937,7 +937,7 @@ uint8_t API_EXPORTED libusb_get_port_number(libusb_device *dev)
 /** \ingroup libusb_dev
  * Get the list of all port numbers from root for the specified device
  *
- * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
  * \param dev a device
  * \param port_numbers the array that should contain the port numbers
  * \param port_numbers_len the maximum length of the array. As per the USB 3.0
@@ -1224,7 +1224,7 @@ out:
  * libusb_set_iso_packet_lengths() in order to set the length field of every
  * isochronous packet in a transfer.
  *
- * Since v1.0.27.
+ * Since version 1.0.27, \ref LIBUSB_API_VERSION >= 0x0100010A
  *
  * \param dev a device
  * \param interface_number the <tt>bInterfaceNumber</tt> of the interface
@@ -2205,7 +2205,7 @@ int API_EXPORTED libusb_set_auto_detach_kernel_driver(
 }
 
 /** \ingroup libusb_lib
- * \deprecated Use libusb_set_option() or libusb_init_context() instead
+ * Deprecated. Use libusb_set_option() or libusb_init_context() instead
  * using the \ref LIBUSB_OPTION_LOG_LEVEL option.
  */
 void API_EXPORTED libusb_set_debug(libusb_context *ctx, int level)
@@ -2395,18 +2395,9 @@ static enum libusb_log_level get_env_debug_level(void)
 #endif
 
 /** \ingroup libusb_lib
- * Initialize libusb. This function must be called before calling any other
- * libusb function.
- *
- * If you do not provide an output location for a context pointer, a default
- * context will be created. If there was already a default context, it will
- * be reused (and nothing will be initialized/reinitialized). Deprecated in
- * favor of \ref libusb_init_context().
+ * Deprecated initialization function. Equivalent to calling libusb_init_context with no options.
  *
- * \param ctx Optional output location for context pointer.
- * Only valid on return code 0.
- * \returns 0 on success, or a LIBUSB_ERROR code on failure
- * \see libusb_contexts
+ * \see libusb_init_context
  */
 int API_EXPORTED libusb_init(libusb_context **ctx)
 {
@@ -2422,6 +2413,8 @@ int API_EXPORTED libusb_init(libusb_context **ctx)
  * be reused (and nothing will be initialized/reinitialized and options will
  * be ignored). If num_options is 0 then options is ignored and may be NULL.
  *
+ * Since version 1.0.27, \ref LIBUSB_API_VERSION >= 0x0100010A
+ *
  * \param ctx Optional output location for context pointer.
  * Only valid on return code 0.
  * \param options Optional array of options to set on the new context.
@@ -2650,7 +2643,7 @@ void API_EXPORTED libusb_exit(libusb_context *ctx)
 
 /** \ingroup libusb_misc
  * Check at runtime if the loaded library has a given capability.
- * This call should be performed after \ref libusb_init(), to ensure the
+ * This call should be performed after \ref libusb_init_context(), to ensure the
  * backend has updated its capability set.
  *
  * \param capability the \ref libusb_capability to check for
diff --git a/libusb/descriptor.c b/libusb/descriptor.c
index 6a0f29a..4623ad1 100644
--- a/libusb/descriptor.c
+++ b/libusb/descriptor.c
@@ -521,7 +521,7 @@ static int get_config_descriptor(struct libusb_device *dev, uint8_t config_idx,
  *
  * This is a non-blocking function; the device descriptor is cached in memory.
  *
- * Note since libusb-1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, this
+ * Note since libusb-1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, this
  * function always succeeds.
  *
  * \param dev the device
@@ -1073,6 +1073,8 @@ void API_EXPORTED libusb_free_container_id_descriptor(
 /** \ingroup libusb_desc
  * Get a platform descriptor
  *
+ * Since version 1.0.27, \ref LIBUSB_API_VERSION >= 0x0100010A
+ *
  * \param ctx the context to operate on, or NULL for the default context
  * \param dev_cap Device Capability descriptor with a bDevCapabilityType of
  * \ref libusb_capability_type::LIBUSB_BT_PLATFORM_DESCRIPTOR
diff --git a/libusb/hotplug.c b/libusb/hotplug.c
index 0b34e9f..3c64f69 100644
--- a/libusb/hotplug.c
+++ b/libusb/hotplug.c
@@ -33,7 +33,7 @@
  *
  * \section hotplug_intro Introduction
  *
- * Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support
+ * Version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, has added support
  * 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).
@@ -117,7 +117,7 @@ int main (void) {
   libusb_hotplug_callback_handle callback_handle;
   int rc;
 
-  libusb_init(NULL);
+  libusb_init_context(NULL, NULL, 0);
 
   rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
                                         LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
diff --git a/libusb/io.c b/libusb/io.c
index d0e1aef..ab84ba6 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -2628,11 +2628,11 @@ int API_EXPORTED libusb_get_next_timeout(libusb_context *ctx,
  * To remove notifiers, pass NULL values for the function pointers.
  *
  * Note that file descriptors may have been added even before you register
- * these notifiers (e.g. at libusb_init() time).
+ * these notifiers (e.g. at libusb_init_context() time).
  *
  * Additionally, note that the removal notifier may be called during
  * libusb_exit() (e.g. when it is closing file descriptors that were opened
- * and added to the poll set at libusb_init() time). If you don't want this,
+ * and added to the poll set at libusb_init_context() time). If you don't want this,
  * remove the notifiers immediately before calling libusb_exit().
  *
  * \param ctx the context to operate on, or NULL for the default context
diff --git a/libusb/libusb.h b/libusb/libusb.h
index 038e5f3..8a2deb7 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -130,12 +130,15 @@ typedef SSIZE_T ssize_t;
  * \ingroup libusb_misc
  * libusb's API version.
  *
- * Since version 1.0.13, to help with feature detection, libusb defines
+ * Since version 1.0.18, to help with feature detection, libusb defines
  * a LIBUSB_API_VERSION macro that gets increased every time there is a
  * significant change to the API, such as the introduction of a new call,
  * the definition of a new macro/enum member, or any other element that
  * libusb applications may want to detect at compilation time.
  *
+ * Between versions 1.0.13 and 1.0.17 (inclusive) the older spelling of
+ * LIBUSBX_API_VERSION was used.
+ *
  * The macro is typically used in an application as follows:
  * \code
  * #if defined(LIBUSB_API_VERSION) && (LIBUSB_API_VERSION >= 0x01001234)
@@ -145,10 +148,34 @@ typedef SSIZE_T ssize_t;
  *
  * Internally, LIBUSB_API_VERSION is defined as follows:
  * (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
+ *
+ * The incremental component has changed as follows:
+ * <ul>
+ * <li>libusbx version 1.0.13: LIBUSBX_API_VERSION = 0x01000100
+ * <li>libusbx version 1.0.14: LIBUSBX_API_VERSION = 0x010000FF
+ * <li>libusbx version 1.0.15: LIBUSBX_API_VERSION = 0x01000101
+ * <li>libusbx version 1.0.16: LIBUSBX_API_VERSION = 0x01000102
+ * <li>libusbx version 1.0.17: LIBUSBX_API_VERSION = 0x01000102
+ * <li>libusb version 1.0.18: LIBUSB_API_VERSION = 0x01000102
+ * <li>libusb version 1.0.19: LIBUSB_API_VERSION = 0x01000103
+ * <li>libusb version 1.0.20: LIBUSB_API_VERSION = 0x01000104
+ * <li>libusb version 1.0.21: LIBUSB_API_VERSION = 0x01000105
+ * <li>libusb version 1.0.22: LIBUSB_API_VERSION = 0x01000106
+ * <li>libusb version 1.0.23: LIBUSB_API_VERSION = 0x01000107
+ * <li>libusb version 1.0.24: LIBUSB_API_VERSION = 0x01000108
+ * <li>libusb version 1.0.25: LIBUSB_API_VERSION = 0x01000109
+ * <li>libusb version 1.0.26: LIBUSB_API_VERSION = 0x01000109
+ * <li>libusb version 1.0.27: LIBUSB_API_VERSION = 0x0100010A
+ * </ul>
  */
 #define LIBUSB_API_VERSION 0x0100010A
 
-/* The following is kept for compatibility, but will be deprecated in the future */
+/** \def LIBUSBX_API_VERSION
+ * \ingroup libusb_misc
+ *
+ * This is the older spelling, kept for backwards compatibility of code
+ * needing to test for older library versions where the newer spelling
+ * did not exist. */
 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
 
 #if defined(__cplusplus)
@@ -1081,7 +1108,7 @@ struct libusb_version {
  * libusb_exit() will not destroy resources that the other user is still
  * using.
  *
- * Sessions are created by libusb_init() and destroyed through libusb_exit().
+ * Sessions are created by libusb_init_context() and destroyed through libusb_exit().
  * If your application is guaranteed to only ever include a single libusb
  * user (i.e. you), you do not have to worry about contexts: pass NULL in
  * every function call where a context is required, and the default context
@@ -1461,22 +1488,21 @@ enum libusb_option {
 	 * your software.
 	 *
 	 * If the LIBUSB_DEBUG environment variable was set when libusb was
-	 * initialized, this function does nothing: the message verbosity is fixed
+	 * initialized, this option does nothing: the message verbosity is fixed
 	 * to the value in the environment variable.
 	 *
-	 * If libusb was compiled without any message logging, this function does
+	 * If libusb was compiled without any message logging, this option does
 	 * nothing: you'll never get any messages.
 	 *
-	 * If libusb was compiled with verbose debug message logging, this function
+	 * If libusb was compiled with verbose debug message logging, this option
 	 * does nothing: you'll always get messages from all levels.
 	 */
 	LIBUSB_OPTION_LOG_LEVEL = 0,
 
 	/** Use the UsbDk backend for a specific context, if available.
 	 *
-	 * This option should be set immediately after calling libusb_init(), or set at
-	 * initialization with libusb_init_context() otherwise unspecified behavior
-	 * may occur.
+	 * This option should be set at initialization with libusb_init_context()
+	 * otherwise unspecified behavior may occur.
 	 *
 	 * Only valid on Windows. Ignored on all other platforms.
 	 */
@@ -1495,6 +1521,9 @@ enum libusb_option {
 	 * This is typically needed on Android, where access to USB devices
 	 * is limited.
 	 *
+	 * This option should only be used with libusb_init_context()
+	 * otherwise unspecified behavior may occur.
+	 *
 	 * Only valid on Linux. Ignored on all other platforms.
 	 */
 	LIBUSB_OPTION_NO_DEVICE_DISCOVERY = 2,
diff --git a/libusb/strerror.c b/libusb/strerror.c
index 847b106..eb35503 100644
--- a/libusb/strerror.c
+++ b/libusb/strerror.c
@@ -160,7 +160,7 @@ static const char * const (*usbi_error_strings)[LIBUSB_ERROR_COUNT] = &usbi_loca
  * If libusb_setlocale() is not called, all messages will be in English.
  *
  * The following functions return translatable strings: libusb_strerror().
- * Note that the libusb log messages controlled through libusb_set_debug()
+ * Note that the libusb log messages controlled through LIBUSB_OPTION_LOG_LEVEL
  * are not translated, they are always in English.
  *
  * For POSIX UTF-8 environments if you want libusb to follow the standard
diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index f0d379e..22e0794 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 11873
+#define LIBUSB_NANO 11874