From 32895e5b65c2cc90bd504261728bf3cf30c3f0b8 Mon Sep 17 00:00:00 2001
From: DarkCat09 <gh@dc09.ru>
Date: Fri, 9 Aug 2024 11:16:38 +0400
Subject: [PATCH] docs: add doc-comments to rewritten certs::fingerprint

---
 src/certs/fingerprint.rs | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/certs/fingerprint.rs b/src/certs/fingerprint.rs
index b25f01e..110c4e2 100644
--- a/src/certs/fingerprint.rs
+++ b/src/certs/fingerprint.rs
@@ -13,17 +13,30 @@ pub const SHA512_HEX_LEN: usize = 128; // (512 / 8) * 2
 pub const SHA256_B64_LEN: usize = 44; // 4 * ((256 / 8) as f64 / 3 as f64).ceil()
 pub const SHA512_B64_LEN: usize = 88; // 4 * ((512 / 8) as f64 / 3 as f64).ceil()
 
+/// Supported hashing algorithms
 #[derive(Debug, Clone, Copy)]
 pub enum HashAlgo {
     Sha256,
     Sha512,
 }
 
+/// Structure holding a TLS cert hash
+/// and providing bin2text methods,
+/// mostly for use in [`crate::certs::SelfsignedCertVerifier`]
 pub struct CertFingerprint<T: Digest> {
     hash: sha2::digest::Output<T>,
 }
 
 impl<T: Digest> CertFingerprint<T> {
+    /// Generate a TLS cert hash.
+    ///
+    /// # Examples
+    /// ```
+    /// use tokio_gemini::certs::fingerprint::{CertFingerprint, Sha256};
+    ///
+    /// let hash = CertFingerprint::<Sha256>::new(rustls_cert);
+    /// let fingerprint = hash.base64();
+    /// ```
     pub fn new(cert: &CertificateDer) -> Self {
         let mut hasher = T::new();
         for chunk in cert.chunks(128) {
@@ -36,11 +49,15 @@ impl<T: Digest> CertFingerprint<T> {
 }
 
 impl CertFingerprint<Sha256> {
+    /// Encode the TLS cert SHA-256 hash as HEX (base16).
+    /// Resulting string is 64 bytes length.
     pub fn hex(&self) -> String {
         let mut buf = [0u8; SHA256_HEX_LEN];
         b16::encode_str(&self.hash, &mut buf).unwrap().to_owned()
     }
 
+    /// Encode the TLS cert SHA-256 hash as base64.
+    /// Resulting string is 44 bytes length.
     pub fn base64(&self) -> String {
         let mut buf = [0u8; SHA256_B64_LEN];
         b64::encode(&self.hash, &mut buf).unwrap().to_owned()
@@ -48,11 +65,15 @@ impl CertFingerprint<Sha256> {
 }
 
 impl CertFingerprint<Sha512> {
+    /// Encode the TLS cert SHA-512 hash as HEX (base16).
+    /// Resulting string is 128 bytes length.
     pub fn hex(&self) -> String {
         let mut buf = [0u8; SHA512_HEX_LEN];
         b16::encode_str(&self.hash, &mut buf).unwrap().to_owned()
     }
 
+    /// Encode the TLS cert SHA-512 hash as base64.
+    /// Resulting string is 88 bytes length.
     pub fn base64(&self) -> String {
         let mut buf = [0u8; SHA512_B64_LEN];
         b64::encode(&self.hash, &mut buf).unwrap().to_owned()