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, 64 insertions, 13 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 8b0aae5..36a1dfd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -9,13 +9,16 @@
 //! performed without authentication, some require user access, and some require admin access.
 //! This is modelled using the types [`User`][] and [`Admin`][].
 //!
-//! Use [`connect`][] to connect to any Nitrokey device.  The method will return a
+//! You can only connect to one Nitrokey at a time.  Use the global [`take`][] function to obtain
+//! an reference to the [`Manager`][] singleton that keeps track of the connections.  Then use the
+//! [`connect`][] method to connect to any Nitrokey device.  The method will return a
 //! [`DeviceWrapper`][] that abstracts over the supported Nitrokey devices.  You can also use
-//! [`Pro::connect`][] or [`Storage::connect`][] to connect to a specific device.
+//! [`connect_model`][], [`connect_pro`][] or [`connect_storage`][] to connect to a specific
+//! device.
 //!
-//! You can then use [`authenticate_user`][] or [`authenticate_admin`][] to get an authenticated
-//! device that can perform operations that require authentication.  You can use [`device`][] to go
-//! back to the unauthenticated device.
+//! You can call [`authenticate_user`][] or [`authenticate_admin`][] to get an authenticated device
+//! that can perform operations that require authentication.  You can use [`device`][] to go back
+//! to the unauthenticated device.
 //!
 //! This makes sure that you can only execute a command if you have the required access rights.
 //! Otherwise, your code will not compile.  The only exception are the methods to generate one-time
@@ -31,7 +34,8 @@
 //! # use nitrokey::Error;
 //!
 //! # fn try_main() -> Result<(), Error> {
-//! let device = nitrokey::connect()?;
+//! let mut manager = nitrokey::take()?;
+//! let device = manager.connect()?;
 //! println!("{}", device.get_serial_number()?);
 //! #     Ok(())
 //! # }
@@ -44,7 +48,8 @@
 //! # use nitrokey::Error;
 //!
 //! # fn try_main() -> Result<(), Error> {
-//! let device = nitrokey::connect()?;
+//! let mut manager = nitrokey::take()?;
+//! let device = manager.connect()?;
 //! let slot_data = OtpSlotData::new(1, "test", "01234567890123456689", OtpMode::SixDigits);
 //! match device.authenticate_admin("12345678") {
 //!     Ok(mut admin) => {
@@ -66,7 +71,8 @@
 //! # 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.get_hotp_code(1) {
 //!     Ok(code) => println!("Generated HOTP code: {}", code),
 //!     Err(err) => eprintln!("Could not generate HOTP code: {}", err),
@@ -77,9 +83,12 @@
 //!
 //! [`authenticate_admin`]: trait.Authenticate.html#method.authenticate_admin
 //! [`authenticate_user`]: trait.Authenticate.html#method.authenticate_user
-//! [`connect`]: fn.connect.html
-//! [`Pro::connect`]: struct.Pro.html#fn.connect.html
-//! [`Storage::connect`]: struct.Storage.html#fn.connect.html
+//! [`take`]: fn.take.html
+//! [`connect`]: struct.Manager.html#method.connect
+//! [`connect_model`]: struct.Manager.html#method.connect_model
+//! [`connect_pro`]: struct.Manager.html#method.connect_pro
+//! [`connect_storage`]: struct.Manager.html#method.connect_storage
+//! [`manager`]: trait.Device.html#method.manager
 //! [`device`]: struct.User.html#method.device
 //! [`get_hotp_code`]: trait.GenerateOtp.html#method.get_hotp_code
 //! [`get_totp_code`]: trait.GenerateOtp.html#method.get_totp_code
@@ -163,9 +172,50 @@ impl fmt::Display for Version {
 /// manager struct makes sure that `nitrokey-rs` does not try to connect to two devices at the same
 /// time.
 ///
-/// To obtain an instance of this manager, use the [`take`][] function.
+/// To obtain a reference to an instance of this manager, use the [`take`][] function.  Use one of
+/// the connect methods – [`connect`][], [`connect_model`][], [`connect_pro`][] or
+/// [`connect_storage`][] – to retrieve a [`Device`][] instance.
 ///
+/// # Examples
+///
+/// Connect to a single device:
+///
+/// ```no_run
+/// use nitrokey::Device;
+/// # use nitrokey::Error;
+///
+/// # fn try_main() -> Result<(), Error> {
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect()?;
+/// println!("{}", device.get_serial_number()?);
+/// #     Ok(())
+/// # }
+/// ```
+///
+/// Connect to a Pro and a Storage device:
+///
+/// ```no_run
+/// use nitrokey::{Device, Model};
+/// # use nitrokey::Error;
+///
+/// # fn try_main() -> Result<(), Error> {
+/// let mut manager = nitrokey::take()?;
+/// let device = manager.connect_model(Model::Pro)?;
+/// println!("Pro: {}", device.get_serial_number()?);
+/// drop(device);
+/// let device = manager.connect_model(Model::Storage)?;
+/// println!("Storage: {}", device.get_serial_number()?);
+/// #     Ok(())
+/// # }
+/// ```
+///
+/// [`connect`]: #method.connect
+/// [`connect_model`]: #method.connect_model
+/// [`connect_pro`]: #method.connect_pro
+/// [`connect_storage`]: #method.connect_storage
+/// [`manager`]: trait.Device.html#method.manager
 /// [`take`]: fn.take.html
+/// [`Device`]: trait.Device.html
 #[derive(Debug)]
 pub struct Manager {
     marker: marker::PhantomData<()>,
@@ -195,7 +245,8 @@ impl Manager {
     /// fn do_something(device: DeviceWrapper) {}
     ///
     /// # fn main() -> Result<(), nitrokey::Error> {
-    /// match nitrokey::take()?.connect() {
+    /// let mut manager = nitrokey::take()?;
+    /// match manager.connect() {
     ///     Ok(device) => do_something(device),
     ///     Err(err) => println!("Could not connect to a Nitrokey: {}", err),
     /// }