docs: add details for client login final step (#358)

This tweaks the documentation on the main module, in order to
add some details on the outcome of the client login final step.
In particular, it clarifies the result of `ClientLogin::finish()`
both on success and on errors and it adds some intra-crate links
to the relevant structures and fields.

src/lib.rs

@@ -390,11 +390,18 @@
 //!
 //! ### Client Login Finish
 //! In the third step of login, the client takes as input a
-//! [`CredentialResponse`] from the server. The client runs
+//! [`CredentialResponse`] from the server and runs [`ClientLogin::finish`]
-//! [`ClientLogin::finish`] and produces an output consisting of a
+//! on it.
-//! [`CredentialFinalization`] to be sent to the server to complete the
+//! If the authentication is successful, then the client obtains a
-//! protocol, the `session_key` sequence of bytes which will match the server's
+//! [`ClientLoginFinishResult`]. Otherwise, on failure, the
-//! session key upon a successful login.
+//! algorithm outputs an
+//! [`InvalidLoginError`](errors::ProtocolError::InvalidLoginError) error.
+//!
+//! The resulting [`ClientLoginFinishResult`] obtained by client in this step
+//! contains, among other things, a [`CredentialFinalization`] to be sent to the
+//! server to complete the protocol, and a
+//! [`session_key`](struct.ClientLoginFinishResult.html#structfield.session_key)
+//! which will match the server's session key upon a successful login.
 //! ```
 //! # use opaque_ke::{
 //! #   errors::ProtocolError,
@@ -1108,8 +1115,8 @@
 //!   and `OprfCs`. To select a specific backend see the [curve25519-dalek]
 //!   documentation.
 //!
-//! - The `curve25519` feature enables [`Curve25519`] as a `KeGroup`. To select
+//! - The `curve25519` feature enables Curve25519 as a `KeGroup`. To select a
-//!   a specific backend see the [curve25519-dalek] documentation.
+//!   specific backend see the [curve25519-dalek] documentation.
 //!
 //! - The `p256` feature enables the use of [`p256::NistP256`] as a `KeGroup`
 //!   and a `OprfCs` for `CipherSuite`.