From e9a99a86e523b7ae8736d07d8a32046191ecd9f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Fri, 29 Nov 2024 15:43:25 +0100
Subject: [PATCH] WIP docs

---
 src/lib.rs | 12 ++++++++++++
 src/sas.rs | 19 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 0894407..5fa19be 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -9,6 +9,18 @@ mod types;
 use error::*;
 use pyo3::{prelude::*, types::PyBytes};
 
+/// A Rust implementation of Olm and Megolm
+///
+/// vodozemac is a Rust reimplementation of [libolm](https://gitlab.matrix.org/matrix-org/olm), a
+/// cryptographic library used for end-to-end encryption in [Matrix](https://matrix.org). At its
+/// core, it is an implementation of the Olm and Megolm cryptographic ratchets,
+/// along with a high-level API to easily establish cryptographic communication
+/// channels employing those ratchets with other parties. It also implements
+/// some other miscellaneous cryptographic functionality which is useful for
+/// building Matrix clients, such as [SAS][sas].
+///
+/// [sas]:
+/// <https://spec.matrix.org/v1.2/client-server-api/#short-authentication-string-sas-verification>
 #[pymodule(name = "vodozemac")]
 fn my_module(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<account::Account>()?;
diff --git a/src/sas.rs b/src/sas.rs
index 86c8341..05aa623 100644
--- a/src/sas.rs
+++ b/src/sas.rs
@@ -2,6 +2,10 @@ use pyo3::prelude::*;
 
 use crate::{error::SasError, types::Curve25519PublicKey};
 
+/// A class representing a short auth string verification object.
+///
+/// This object can be used to establish a shared secret to perform the short
+/// auth string based key verification.
 #[pyclass]
 pub struct Sas {
     inner: Option<vodozemac::sas::Sas>,
@@ -10,6 +14,10 @@ pub struct Sas {
 
 #[pymethods]
 impl Sas {
+    /// Create a new random verification object
+    ///
+    /// This creates an ephemeral Curve25519 keypair that can be used to
+    /// establish a shared secret.
     #[new]
     fn new() -> Self {
         let sas = vodozemac::sas::Sas::new();
@@ -18,11 +26,17 @@ impl Sas {
         Self { inner: Some(sas), public_key }
     }
 
+    /// The public key that can be used to establish a shared secret.
     #[getter]
     fn public_key(&self) -> Curve25519PublicKey {
         self.public_key.into()
     }
 
+    /// Establishes a SAS secret by performing a DH handshake with another
+    /// public key.
+    ///
+    /// Returns an [`EstablishedSas`] object which can be used to generate
+    /// [`SasBytes`] if the given public key was valid, otherwise `None`.
     fn diffie_hellman(&mut self, key: Curve25519PublicKey) -> Result<EstablishedSas, SasError> {
         if let Some(sas) = self.inner.take() {
             let sas = sas.diffie_hellman(key.inner)?;
@@ -34,6 +48,11 @@ impl Sas {
     }
 }
 
+/// A class representing a short auth string verification object where the
+/// shared secret has been established.
+///
+/// This object can be used to generate the short auth string and calculate and
+/// verify a MAC that protects information about the keys being verified.
 #[pyclass]
 pub struct EstablishedSas {
     inner: vodozemac::sas::EstablishedSas,