From a21678e96970ada5040f004404cdd0a89a0362cf Mon Sep 17 00:00:00 2001
From: Luca Bruno <lucab@lucabruno.net>
Date: Wed, 18 Sep 2024 22:04:14 +0200
Subject: [PATCH] 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 | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 2599a52..e00c8ff 100644
--- a/src/lib.rs
+++ b/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
-//! [`ClientLogin::finish`] and produces an output consisting of a
-//! [`CredentialFinalization`] to be sent to the server to complete the
-//! protocol, the `session_key` sequence of bytes which will match the server's
-//! session key upon a successful login.
+//! [`CredentialResponse`] from the server and runs [`ClientLogin::finish`]
+//! on it.
+//! If the authentication is successful, then the client obtains a
+//! [`ClientLoginFinishResult`]. Otherwise, on failure, the
+//! 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
-//!   a specific backend see the [curve25519-dalek] documentation.
+//! - The `curve25519` feature enables Curve25519 as a `KeGroup`. To select a
+//!   specific backend see the [curve25519-dalek] documentation.
 //!
 //! - The `p256` feature enables the use of [`p256::NistP256`] as a `KeGroup`
 //!   and a `OprfCs` for `CipherSuite`.