From 8be0a579dbd51f3d1d420511e44faddd347721e5 Mon Sep 17 00:00:00 2001
From: Jason Volk <jason@zemos.net>
Date: Thu, 15 Jan 2026 21:24:10 +0000
Subject: [PATCH] Add doc comments to SSO related interface routines.

Signed-off-by: Jason Volk <jason@zemos.net>
---
 src/service/oauth/mod.rs       | 15 +++++++++++++++
 src/service/oauth/providers.rs |  4 ++++
 2 files changed, 19 insertions(+)

diff --git a/src/service/oauth/mod.rs b/src/service/oauth/mod.rs
index b69f85ac..d2ef86cf 100644
--- a/src/service/oauth/mod.rs
+++ b/src/service/oauth/mod.rs
@@ -46,6 +46,8 @@ impl crate::Service for Service {
 	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
 }
 
+/// Network request to a Provider returning userinfo for a Session. The session
+/// must have a valid access token.
 #[implement(Service)]
 #[tracing::instrument(level = "debug", skip_all, ret)]
 pub async fn request_userinfo(
@@ -66,6 +68,8 @@ pub async fn request_userinfo(
 		.log_err()
 }
 
+/// Network request to a Provider returning information for a Session based on
+/// its access token.
 #[implement(Service)]
 #[tracing::instrument(level = "debug", skip_all, ret)]
 pub async fn request_tokeninfo(
@@ -88,6 +92,7 @@ pub async fn request_tokeninfo(
 		.log_err()
 }
 
+/// Network request to a Provider revoking a Session's token.
 #[implement(Service)]
 #[tracing::instrument(level = "debug", skip_all, ret)]
 pub async fn revoke_token(&self, (provider, session): (&Provider, &Session)) -> Result {
@@ -115,6 +120,8 @@ pub async fn revoke_token(&self, (provider, session): (&Provider, &Session)) ->
 		.map(|_| ())
 }
 
+/// Network request to a Provider to obtain an access token for a Session using
+/// a provided code.
 #[implement(Service)]
 #[tracing::instrument(level = "debug", skip_all, ret)]
 pub async fn request_token(
@@ -224,21 +231,29 @@ pub async fn get_user(&self, user_id: &UserId) -> Result<(Provider, Session)> {
 	Ok((provider, session))
 }
 
+/// Generate a unique-id string determined by the combination of `Provider` and
+/// `Session` instances.
 #[inline]
 pub fn unique_id((provider, session): (&Provider, &Session)) -> Result<String> {
 	unique_id_parts((provider, session)).and_then(unique_id_iss_sub)
 }
 
+/// Generate a unique-id string determined by the combination of `Provider`
+/// instance and `sub` string.
 #[inline]
 pub fn unique_id_sub((provider, sub): (&Provider, &str)) -> Result<String> {
 	unique_id_sub_parts((provider, sub)).and_then(unique_id_iss_sub)
 }
 
+/// Generate a unique-id string determined by the combination of `issuer_url`
+/// and `Session` instance.
 #[inline]
 pub fn unique_id_iss((iss, session): (&str, &Session)) -> Result<String> {
 	unique_id_iss_parts((iss, session)).and_then(unique_id_iss_sub)
 }
 
+/// Generate a unique-id string determined by the `issuer_url` and the `sub`
+/// strings directly.
 pub fn unique_id_iss_sub((iss, sub): (&str, &str)) -> Result<String> {
 	let hash = sha256::delimited([iss, sub].iter());
 	let b64 = b64encode.encode(hash);
diff --git a/src/service/oauth/providers.rs b/src/service/oauth/providers.rs
index cac599e7..e419510e 100644
--- a/src/service/oauth/providers.rs
+++ b/src/service/oauth/providers.rs
@@ -164,6 +164,8 @@ async fn configure(&self, mut provider: Provider) -> Result<Provider> {
 	Ok(provider)
 }
 
+/// Send a network request to a provider at the computed location of the
+/// `.well-known/openid-configuration`, returning the configuration.
 #[implement(Providers)]
 #[tracing::instrument(level = "debug", ret(level = "trace"), skip(self))]
 pub async fn discover(&self, provider: &Provider) -> Result<JsonValue> {
@@ -179,6 +181,8 @@ pub async fn discover(&self, provider: &Provider) -> Result<JsonValue> {
 		.map_err(Into::into)
 }
 
+/// Compute the location of the `/.well-known/openid-configuration` based on the
+/// local provider config.
 fn discovery_url(provider: &Provider) -> Result<Url> {
 	let default_url = provider
 		.discovery