docs: add doc-comments to lib.rs and client

src/client/builder.rs

@@ -20,12 +20,15 @@ pub struct ClientBuilder {
 }
 
 impl Default for ClientBuilder {
+    /// Same as [`ClientBuilder::new()`].
     fn default() -> Self {
         Self::new()
     }
 }
 
 impl ClientBuilder {
+    /// Instantiate a builder with empty [`rustls::RootCertStore`],
+    /// no cert verifiers and default TLS versions.
     pub fn new() -> Self {
         ClientBuilder {
             root_certs: rustls::RootCertStore::empty(),
@@ -35,6 +38,7 @@ impl ClientBuilder {
         }
     }
 
+    /// Construct a [`Client`] from the configuration.
     pub fn build(self) -> Client {
         let provider = rustls::crypto::CryptoProvider::get_default()
             .cloned()
@@ -82,12 +86,17 @@ impl ClientBuilder {
         Client::from(tls_config)
     }
 
+    /// Include webpki trust anchors.
+    /// Not recommended (useless) as most Gemini capsules use self-signed
+    /// TLS certs and properly configured TOFU policy is enough.
     pub fn with_webpki_roots(mut self) -> Self {
         self.root_certs
             .extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
         self
     }
 
+    /// Include custom trust anchors.
+    /// Not recommended (useless), see note for [`ClientBuilder::with_webpki_roots`].
     pub fn with_custom_roots(
         mut self,
         iter: impl IntoIterator<Item = TrustAnchor<'static>>,
@@ -96,6 +105,10 @@ impl ClientBuilder {
         self
     }
 
+    /// Include a self-signed cert verifier.
+    /// If you only need a known_hosts file, consider using
+    /// [`crate::certs::file_sscv::FileBasedCertVerifier`],
+    /// it will do all the work for you.
     pub fn with_selfsigned_cert_verifier(
         mut self,
         ss_verifier: impl SelfsignedCertVerifier + 'static,
@@ -104,6 +117,10 @@ impl ClientBuilder {
         self
     }
 
+    /// Include a custom TLS cert verifier implementing rustls' [`ServerCertVerifier`].
+    /// Normally need to be used only for [`crate::certs::insecure::AllowAllCertVerifier`].
+    /// Note: the webpki verifier and a self-signed cert verifier are not called
+    /// when a custom verifier is set.
     pub fn with_custom_verifier(
         mut self,
         custom_verifier: impl ServerCertVerifier + 'static,
@@ -112,6 +129,8 @@ impl ClientBuilder {
         self
     }
 
+    /// Limit the supported TLS versions list to the specified ones.
+    /// Default is [`rustls::DEFAULT_VERSIONS`].
     pub fn with_tls_versions(
         mut self,
         versions: &'static [&'static SupportedProtocolVersion],