From 0f0fd3ecb1d313cdff3fa8e1dd30348e37b40650 Mon Sep 17 00:00:00 2001
From: Joe Birr-Pixton <jpixton@gmail.com>
Date: Sun, 20 Oct 2024 19:34:16 +0100
Subject: [PATCH] chacha20poly1305: docs

---
 graviola/src/mid/chacha20poly1305.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/graviola/src/mid/chacha20poly1305.rs b/graviola/src/mid/chacha20poly1305.rs
index d7120683..ca8675f7 100644
--- a/graviola/src/mid/chacha20poly1305.rs
+++ b/graviola/src/mid/chacha20poly1305.rs
@@ -6,15 +6,27 @@ use crate::low::poly1305::Poly1305;
 use crate::low::{ct_equal, zeroise, Entry};
 use crate::Error;
 
+/// A chacha20poly1305 key.
+///
+/// See [RFC7539](https://datatracker.ietf.org/doc/html/rfc7539).
 pub struct ChaCha20Poly1305 {
     key: [u8; 32],
 }
 
 impl ChaCha20Poly1305 {
+    /// Create a new [`ChaCha20Poly1305`] from 32 bytes of key material.
     pub fn new(key: [u8; 32]) -> Self {
         Self { key }
     }
 
+    /// Encrypt the given message.
+    ///
+    /// On entry, `cipher_inout` contains the plaintext of the message.
+    /// `nonce` contains the nonce, which must be unique for a given key.
+    /// `aad` is the additionally-authenticated data.  It may be empty.
+    ///
+    /// On exit, `cipher_inout` contains the ciphertext of the message,
+    /// and `tag_out` contains the authentication tag.
     pub fn encrypt(
         &self,
         nonce: &[u8; 12],
@@ -26,6 +38,18 @@ impl ChaCha20Poly1305 {
         self.cipher(nonce, aad, cipher_inout, tag_out, true);
     }
 
+    /// Decrypts and verifies the given message.
+    ///
+    /// On entry, `cipher_inout` contains the ciphertext of the message.
+    /// `nonce` contains the nonce, which must match what was supplied
+    /// when encrypting this message.
+    /// `aad` is the additionally-authenticated data.  It may be empty.
+    /// `tag` is the purported authentication tag.
+    ///
+    /// On success, `cipher_inout` contains the plaintext of the message,
+    /// and `Ok(())` is returned.
+    /// Otherwise, `Ok(Error::DecryptFailed)` is returned and `cipher_inout`
+    /// is cleared.
     pub fn decrypt(
         &self,
         nonce: &[u8; 12],