Update documentation for Manager refactoring

This patch updates the documentation to reflect the latest changes to
connection handling.  It also updates the doc tests to prefer the new
methods over the old ones.

1 files changed, 72 insertions, 45 deletions

diff --git a/src/device.rs b/src/device.rs
index e1a71fa..758d4c1 100644
--- a/src/device.rs
+++ b/src/device.rs
@@ -53,7 +53,7 @@ impl fmt::Display for VolumeMode {
 
 /// A wrapper for a Nitrokey device of unknown type.
 ///
-/// Use the function [`connect`][] to obtain a wrapped instance.  The wrapper implements all traits
+/// Use the [`connect`][] method to obtain a wrapped instance.  The wrapper implements all traits
 /// that are shared between all Nitrokey devices so that the shared functionality can be used
 /// without knowing the type of the underlying device.  If you want to use functionality that is
 /// not available for all devices, you have to extract the device.
@@ -66,11 +66,12 @@ impl fmt::Display for VolumeMode {
 /// use nitrokey::{Authenticate, DeviceWrapper, User};
 /// # use nitrokey::Error;
 ///
-/// fn perform_user_task(device: &User<DeviceWrapper>) {}
+/// fn perform_user_task<'a>(device: &User<'a, DeviceWrapper<'a>>) {}
 /// fn perform_other_task(device: &DeviceWrapper) {}
 ///
 /// # fn try_main() -> Result<(), Error> {
-/// let device = nitrokey::connect()?;
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect()?;
 /// let device = match device.authenticate_user("123456") {
 ///     Ok(user) => {
 ///         perform_user_task(&user);
@@ -96,7 +97,8 @@ impl fmt::Display for VolumeMode {
 /// fn perform_storage_task(device: &Storage) {}
 ///
 /// # fn try_main() -> Result<(), Error> {
-/// let device = nitrokey::connect()?;
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect()?;
 /// perform_common_task(&device);
 /// match device {
 ///     DeviceWrapper::Storage(storage) => perform_storage_task(&storage),
@@ -106,7 +108,7 @@ impl fmt::Display for VolumeMode {
 /// # }
 /// ```
 ///
-/// [`connect`]: fn.connect.html
+/// [`connect`]: struct.Manager.html#method.connect
 #[derive(Debug)]
 pub enum DeviceWrapper<'a> {
     /// A Nitrokey Storage device.
@@ -117,10 +119,9 @@ pub enum DeviceWrapper<'a> {
 
 /// A Nitrokey Pro device without user or admin authentication.
 ///
-/// Use the global function [`connect`][] to obtain an instance wrapper or the method
-/// [`connect`][`Pro::connect`] to directly obtain an instance.  If you want to execute a command
-/// that requires user or admin authentication, use [`authenticate_admin`][] or
-/// [`authenticate_user`][].
+/// Use the [`connect`][] method to obtain an instance wrapper or the [`connect_pro`] method to
+/// directly obtain an instance.  If you want to execute a command that requires user or admin
+/// authentication, use [`authenticate_admin`][] or [`authenticate_user`][].
 ///
 /// # Examples
 ///
@@ -130,11 +131,12 @@ pub enum DeviceWrapper<'a> {
 /// use nitrokey::{Authenticate, User, Pro};
 /// # use nitrokey::Error;
 ///
-/// fn perform_user_task(device: &User<Pro>) {}
+/// fn perform_user_task<'a>(device: &User<'a, Pro<'a>>) {}
 /// fn perform_other_task(device: &Pro) {}
 ///
 /// # fn try_main() -> Result<(), Error> {
-/// let device = nitrokey::Pro::connect()?;
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect_pro()?;
 /// let device = match device.authenticate_user("123456") {
 ///     Ok(user) => {
 ///         perform_user_task(&user);
@@ -152,8 +154,8 @@ pub enum DeviceWrapper<'a> {
 ///
 /// [`authenticate_admin`]: trait.Authenticate.html#method.authenticate_admin
 /// [`authenticate_user`]: trait.Authenticate.html#method.authenticate_user
-/// [`connect`]: fn.connect.html
-/// [`Pro::connect`]: #method.connect
+/// [`connect`]: struct.Manager.html#method.connect
+/// [`connect_pro`]: struct.Manager.html#method.connect_pro
 #[derive(Debug)]
 pub struct Pro<'a> {
     manager: Option<&'a mut crate::Manager>,
@@ -161,10 +163,9 @@ pub struct Pro<'a> {
 
 /// A Nitrokey Storage device without user or admin authentication.
 ///
-/// Use the global function [`connect`][] to obtain an instance wrapper or the method
-/// [`connect`][`Storage::connect`] to directly obtain an instance.  If you want to execute a
-/// command that requires user or admin authentication, use [`authenticate_admin`][] or
-/// [`authenticate_user`][].
+/// Use the [`connect`][] method to obtain an instance wrapper or the [`connect_storage`] method to
+/// directly obtain an instance.  If you want to execute a command that requires user or admin
+/// authentication, use [`authenticate_admin`][] or [`authenticate_user`][].
 ///
 /// # Examples
 ///
@@ -174,11 +175,12 @@ pub struct Pro<'a> {
 /// use nitrokey::{Authenticate, User, Storage};
 /// # use nitrokey::Error;
 ///
-/// fn perform_user_task(device: &User<Storage>) {}
+/// fn perform_user_task<'a>(device: &User<'a, Storage<'a>>) {}
 /// fn perform_other_task(device: &Storage) {}
 ///
 /// # fn try_main() -> Result<(), Error> {
-/// let device = nitrokey::Storage::connect()?;
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect_storage()?;
 /// let device = match device.authenticate_user("123456") {
 ///     Ok(user) => {
 ///         perform_user_task(&user);
@@ -196,8 +198,8 @@ pub struct Pro<'a> {
 ///
 /// [`authenticate_admin`]: trait.Authenticate.html#method.authenticate_admin
 /// [`authenticate_user`]: trait.Authenticate.html#method.authenticate_user
-/// [`connect`]: fn.connect.html
-/// [`Storage::connect`]: #method.connect
+/// [`connect`]: struct.Manager.html#method.connect
+/// [`connect_storage`]: struct.Manager.html#method.connect_storage
 #[derive(Debug)]
 pub struct Storage<'a> {
     manager: Option<&'a mut crate::Manager>,
@@ -326,7 +328,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
     /// println!("Connected to a Nitrokey {}", device.get_model());
     /// #    Ok(())
     /// # }
@@ -342,7 +345,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
     /// match device.get_serial_number() {
     ///     Ok(number) => println!("serial no: {}", number),
     ///     Err(err) => eprintln!("Could not get serial number: {}", err),
@@ -364,7 +368,9 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
+    /// let count = device.get_user_retry_count();
     /// match device.get_user_retry_count() {
     ///     Ok(count) => println!("{} remaining authentication attempts (user)", count),
     ///     Err(err) => eprintln!("Could not get user retry count: {}", err),
@@ -386,7 +392,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
     /// let count = device.get_admin_retry_count();
     /// match device.get_admin_retry_count() {
     ///     Ok(count) => println!("{} remaining authentication attempts (admin)", count),
@@ -408,7 +415,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
     /// match device.get_firmware_version() {
     ///     Ok(version) => println!("Firmware version: {}", version),
     ///     Err(err) => eprintln!("Could not access firmware version: {}", err),
@@ -431,7 +439,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect()?;
     /// let config = device.get_config()?;
     /// println!("numlock binding:          {:?}", config.numlock);
     /// println!("capslock binding:         {:?}", config.capslock);
@@ -465,7 +474,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.change_admin_pin("12345678", "12345679") {
     ///     Ok(()) => println!("Updated admin PIN."),
     ///     Err(err) => eprintln!("Failed to update admin PIN: {}", err),
@@ -498,7 +508,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.change_user_pin("123456", "123457") {
     ///     Ok(()) => println!("Updated admin PIN."),
     ///     Err(err) => eprintln!("Failed to update admin PIN: {}", err),
@@ -531,7 +542,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.unlock_user_pin("12345678", "123456") {
     ///     Ok(()) => println!("Unlocked user PIN."),
     ///     Err(err) => eprintln!("Failed to unlock user PIN: {}", err),
@@ -565,7 +577,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.lock() {
     ///     Ok(()) => println!("Locked the Nitrokey device."),
     ///     Err(err) => eprintln!("Could not lock the Nitrokey device: {}", err),
@@ -596,7 +609,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.factory_reset("12345678") {
     ///     Ok(()) => println!("Performed a factory reset."),
     ///     Err(err) => eprintln!("Could not perform a factory reset: {}", err),
@@ -630,7 +644,8 @@ pub trait Device<'a>: Authenticate<'a> + GetPasswordSafe<'a> + GenerateOtp + fmt
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect()?;
     /// match device.build_aes_key("12345678") {
     ///     Ok(()) => println!("New AES keys have been built."),
     ///     Err(err) => eprintln!("Could not build new AES keys: {}", err),
@@ -795,7 +810,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.change_update_pin("12345678", "87654321") {
     ///     Ok(()) => println!("Updated update PIN."),
     ///     Err(err) => eprintln!("Failed to update update PIN: {}", err),
@@ -832,7 +848,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.enable_firmware_update("12345678") {
     ///     Ok(()) => println!("Nitrokey entered update mode."),
     ///     Err(err) => eprintln!("Could not enter update mode: {}", err),
@@ -866,7 +883,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.enable_encrypted_volume("123456") {
     ///     Ok(()) => println!("Enabled the encrypted volume."),
     ///     Err(err) => eprintln!("Could not enable the encrypted volume: {}", err),
@@ -895,7 +913,8 @@ impl<'a> Storage<'a> {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.enable_encrypted_volume("123456") {
     ///     Ok(()) => {
     ///         println!("Enabled the encrypted volume.");
@@ -941,7 +960,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// device.enable_encrypted_volume("123445")?;
     /// match device.enable_hidden_volume("hidden-pw") {
     ///     Ok(()) => println!("Enabled a hidden volume."),
@@ -974,7 +994,8 @@ impl<'a> Storage<'a> {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// device.enable_encrypted_volume("123445")?;
     /// match device.enable_hidden_volume("hidden-pw") {
     ///     Ok(()) => {
@@ -1021,7 +1042,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// device.enable_encrypted_volume("123445")?;
     /// device.create_hidden_volume(0, 0, 100, "hidden-pw")?;
     /// #     Ok(())
@@ -1061,7 +1083,8 @@ impl<'a> Storage<'a> {
     /// use nitrokey::VolumeMode;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.set_unencrypted_volume_mode("12345678", VolumeMode::ReadWrite) {
     ///     Ok(()) => println!("Set the unencrypted volume to read-write mode."),
     ///     Err(err) => eprintln!("Could not set the unencrypted volume to read-write mode: {}", err),
@@ -1106,7 +1129,8 @@ impl<'a> Storage<'a> {
     /// use nitrokey::VolumeMode;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.set_encrypted_volume_mode("12345678", VolumeMode::ReadWrite) {
     ///     Ok(()) => println!("Set the encrypted volume to read-write mode."),
     ///     Err(err) => eprintln!("Could not set the encrypted volume to read-write mode: {}", err),
@@ -1144,7 +1168,8 @@ impl<'a> Storage<'a> {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect_storage()?;
     /// match device.get_status() {
     ///     Ok(status) => {
     ///         println!("SD card ID: {:#x}", status.serial_number_sd_card);
@@ -1187,7 +1212,8 @@ impl<'a> Storage<'a> {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let device = manager.connect_storage()?;
     /// match device.get_production_info() {
     ///     Ok(data) => {
     ///         println!("SD card ID:   {:#x}", data.sd_card.serial_number);
@@ -1235,7 +1261,8 @@ impl<'a> Storage<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let mut device = nitrokey::Storage::connect()?;
+    /// let mut manager = nitrokey::take()?;
+    /// let mut device = manager.connect_storage()?;
     /// match device.clear_new_sd_card_warning("12345678") {
     ///     Ok(()) => println!("Cleared the new SD card warning."),
     ///     Err(err) => eprintln!("Could not set the clear the new SD card warning: {}", err),