general docs improvements

.github/workflows/docs.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Install zola
         uses: taiki-e/install-action@v2.87.31
         with:
-          tool: zola@0.19.1 # Matched to rustls repo
+          tool: zola@0.23.6
 
       - name: Verify API docs JSON data
         run: |

librustls/src/certificate.rs

@@ -19,7 +19,10 @@ use crate::rslice::rustls_slice_bytes;
 
 /// An X.509 certificate, as used in rustls.
 /// Corresponds to `CertificateDer` in the Rust pki-types API.
-/// <https://docs.rs/rustls-pki-types/latest/rustls_pki_types/struct.CertificateDer.html>
+///
+/// See also the rustls-pki-types documentation for [`CertificateDer`].
+///
+/// [`CertificateDer`]: https://docs.rs/rustls-pki-types/latest/rustls_pki_types/struct.CertificateDer.html
 pub struct rustls_certificate<'a> {
     _private: [u8; 0],
     _marker: PhantomData<&'a ()>,
@@ -30,8 +33,13 @@ impl<'a> Castable for rustls_certificate<'a> {
     type RustType = CertificateDer<'a>;
 }
 
-/// Get the DER data of the certificate itself.
-/// The data is owned by the certificate and has the same lifetime.
+/// Get the certificate's DER data.
+///
+/// On success, `out_der_data` receives a borrowed pointer and `out_der_len` receives its length.
+/// The data remains owned by `cert` and is valid only as long as `cert`. The caller must not
+/// modify or free it.
+///
+/// On error, the output parameters are unchanged.
 #[no_mangle]
 pub extern "C" fn rustls_certificate_get_der(
     cert: *const rustls_certificate,
@@ -58,7 +66,10 @@ pub extern "C" fn rustls_certificate_get_der(
 /// plus a private key that matches the end-entity (leaf) certificate.
 ///
 /// Corresponds to `CertifiedKey` in the Rust API.
-/// <https://docs.rs/rustls/latest/rustls/sign/struct.CertifiedKey.html>
+///
+/// See also the rustls documentation for [`CertifiedKey`].
+///
+/// [`CertifiedKey`]: https://docs.rs/rustls/latest/rustls/sign/struct.CertifiedKey.html
 pub struct rustls_certified_key {
     _private: [u8; 0],
 }
@@ -77,7 +88,7 @@ impl rustls_certified_key {
     /// certificate first.
     ///
     /// `private_key` must point to a buffer of `private_key_len` bytes, containing
-    /// a PEM-encoded private key in either PKCS#1, PKCS#8 or SEC#1 format when
+    /// a PEM-encoded private key in either PKCS#1, PKCS#8, or SEC1 format when
     /// using `aws-lc-rs` as the crypto provider. Supported formats may vary by
     /// provider.
     ///
@@ -91,7 +102,9 @@ impl rustls_certified_key {
     ///
     /// This function does not take ownership of any of its input pointers. It
     /// parses the pointed-to data and makes a copy of the result. You may
-    /// free the cert_chain and private_key pointers after calling it.
+    /// free the `cert_chain` and `private_key` buffers after calling it.
+    ///
+    /// `certified_key_out` is unchanged if the function returns an error.
     ///
     /// Typically, you will build a `rustls_certified_key`, use it to create a
     /// `rustls_server_config` (which increments the reference count), and then
@@ -155,9 +168,14 @@ impl rustls_certified_key {
     /// may retain a pointer to the object. The memory will be freed when all
     /// references are gone.
     ///
-    /// This function does not take ownership of any of its input pointers. It
-    /// parses the pointed-to data and makes a copy of the result. You may
-    /// free the cert_chain and private_key pointers after calling it.
+    /// This function copies the `cert_chain` data and does not take ownership of
+    /// that buffer. Once the `cert_chain` pointer has been validated, the function
+    /// takes ownership of `signing_key`, including when a later operation returns
+    /// an error. The caller must not use or free the signing key afterward. If
+    /// `cert_chain` is NULL, the function returns `RUSTLS_RESULT_NULL_PARAMETER`
+    /// without consuming `signing_key`.
+    ///
+    /// `certified_key_out` is unchanged if the function returns an error.
     ///
     /// Typically, you will build a `rustls_certified_key`, use it to create a
     /// `rustls_server_config` (which increments the reference count), and then
@@ -191,13 +209,13 @@ impl rustls_certified_key {
         }
     }
 
-    /// Return the i-th rustls_certificate in the rustls_certified_key.
+    /// Return the i-th `rustls_certificate` in the `rustls_certified_key`.
     ///
     /// 0 gives the end-entity certificate. 1 and higher give certificates from the chain.
     ///
     /// Indexes higher than the last available certificate return NULL.
     ///
-    /// The returned certificate is valid until the rustls_certified_key is freed.
+    /// The returned certificate is valid until the `rustls_certified_key` is freed.
     #[no_mangle]
     pub extern "C" fn rustls_certified_key_get_certificate<'a>(
         certified_key: *const rustls_certified_key,
@@ -212,14 +230,15 @@ impl rustls_certified_key {
         }
     }
 
-    /// Create a copy of the rustls_certified_key with the given OCSP response data
+    /// Create a copy of the `rustls_certified_key` with the given OCSP response data
     /// as DER encoded bytes.
     ///
     /// The OCSP response may be given as NULL to clear any possibly present OCSP
     /// data from the cloned key.
     ///
-    /// The cloned key is independent from its original and needs to be freed
-    /// by the application.
+    /// The function copies `ocsp_response` and does not take ownership of either input.
+    /// On success, `cloned_key_out` receives an independently owned key that the caller must
+    /// free with `rustls_certified_key_free`. On error, `cloned_key_out` is unchanged.
     #[no_mangle]
     pub extern "C" fn rustls_certified_key_clone_with_ocsp(
         certified_key: *const rustls_certified_key,
@@ -258,12 +277,11 @@ impl rustls_certified_key {
         }
     }
 
-    /// "Free" a certified_key previously returned from `rustls_certified_key_build`.
+    /// Release the caller's reference to a `rustls_certified_key` previously returned from
+    /// `rustls_certified_key_build`.
     ///
-    /// Since certified_key is actually an atomically reference-counted pointer,
-    /// extant certified_key may still hold an internal reference to the Rust object.
-    ///
-    /// However, C code must consider this pointer unusable after "free"ing it.
+    /// Other objects may still hold internal references to the atomically reference-counted
+    /// Rust object. Regardless, the caller must not use `key` after this function returns.
     ///
     /// Calling with NULL is fine. Must not be called twice with the same value.
     #[no_mangle]
@@ -296,11 +314,9 @@ pub(crate) struct RootCertStoreBuilder {
 impl rustls_root_cert_store_builder {
     /// Create a `rustls_root_cert_store_builder`.
     ///
-    /// Caller owns the memory and may free it with `rustls_root_cert_store_free`, regardless of
-    /// whether `rustls_root_cert_store_builder_build` was called.
-    ///
-    /// If you wish to abandon the builder without calling `rustls_root_cert_store_builder_build`,
-    /// it must be freed with `rustls_root_cert_store_builder_free`.
+    /// The caller owns the returned builder and must eventually free it with
+    /// `rustls_root_cert_store_builder_free`, whether or not
+    /// `rustls_root_cert_store_builder_build` is called.
     #[no_mangle]
     pub extern "C" fn rustls_root_cert_store_builder_new() -> *mut rustls_root_cert_store_builder {
         ffi_panic_boundary! {
@@ -318,6 +334,8 @@ impl rustls_root_cert_store_builder {
     /// When `strict` is false, unparseable root certificates will be ignored.
     /// This may be useful on systems that have syntactically invalid root
     /// certificates.
+    ///
+    /// This function copies the parsed certificates and does not retain `pem`.
     #[no_mangle]
     pub extern "C" fn rustls_root_cert_store_builder_add_pem(
         builder: *mut rustls_root_cert_store_builder,
@@ -363,6 +381,9 @@ impl rustls_root_cert_store_builder {
     /// When `strict` is false, unparseable root certificates will be ignored.
     /// This may be useful on systems that have syntactically invalid root
     /// certificates.
+    ///
+    /// `filename` must be a NUL-terminated UTF-8 string. It is borrowed for the
+    /// duration of the call and is not retained.
     #[no_mangle]
     pub extern "C" fn rustls_root_cert_store_builder_load_roots_from_file(
         builder: *mut rustls_root_cert_store_builder,
@@ -411,9 +432,9 @@ impl rustls_root_cert_store_builder {
     ///
     /// The builder is consumed and cannot be used again, but must still be freed.
     ///
-    /// The root cert store can be used in several `rustls_web_pki_client_cert_verifier_builder_new`
-    /// instances and must be freed by the application when no longer needed. See the documentation of
-    /// `rustls_root_cert_store_free` for details about lifetime.
+    /// On success, `root_cert_store_out` receives a new root certificate store. The caller owns
+    /// it and must free it with `rustls_root_cert_store_free` when no longer needed. The store can
+    /// be used in multiple verifier builders.
     #[no_mangle]
     pub extern "C" fn rustls_root_cert_store_builder_build(
         builder: *mut rustls_root_cert_store_builder,
@@ -444,7 +465,10 @@ impl rustls_root_cert_store_builder {
 }
 
 /// A root certificate store.
-/// <https://docs.rs/rustls/latest/rustls/struct.RootCertStore.html>
+///
+/// See also the rustls documentation for [`RootCertStore`].
+///
+/// [`RootCertStore`]: https://docs.rs/rustls/latest/rustls/struct.RootCertStore.html
 pub struct rustls_root_cert_store {
     _private: [u8; 0],
 }
@@ -455,7 +479,8 @@ impl Castable for rustls_root_cert_store {
 }
 
 impl rustls_root_cert_store {
-    /// Free a rustls_root_cert_store previously returned from rustls_root_cert_store_builder_build.
+    /// Free a `rustls_root_cert_store` previously returned from
+    /// `rustls_root_cert_store_builder_build`.
     ///
     /// Calling with NULL is fine. Must not be called twice with the same value.
     #[no_mangle]

librustls/src/cipher.rs

@@ -16,10 +16,12 @@ impl Castable for rustls_supported_ciphersuite {
 }
 
 impl rustls_supported_ciphersuite {
-    /// Return a 16-bit unsigned integer corresponding to this cipher suite's assignment from
-    /// <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4>.
+    /// Return a 16-bit unsigned integer corresponding to this cipher suite's assignment
+    /// in the [IANA TLS Cipher Suites registry].
     ///
     /// The bytes from the assignment are interpreted in network order.
+    ///
+    /// [IANA TLS Cipher Suites registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4
     #[no_mangle]
     pub extern "C" fn rustls_supported_ciphersuite_get_suite(
         supported_ciphersuite: *const rustls_supported_ciphersuite,