docs: clarify freeing client/server builder directly

src/client.rs

@@ -31,9 +31,13 @@ box_castable! {
     /// A client config being constructed. A builder can be modified by,
     /// e.g. rustls_client_config_builder_load_roots_from_file. Once you're
     /// done configuring settings, call rustls_client_config_builder_build
-    /// to turn it into a *rustls_client_config. This object is not safe
-    /// for concurrent mutation. Under the hood, it corresponds to a
-    /// `Box<ClientConfig>`.
+    /// to turn it into a *rustls_client_config.
+    ///
+    /// Alternatively, if an error occurs or, you don't wish to build a config,
+    /// call `rustls_client_config_builder_free` to free the builder directly.
+    ///
+    /// This object is not safe for concurrent mutation. Under the hood,
+    /// it corresponds to a `Box<ClientConfig>`.
     /// <https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html>
     pub struct rustls_client_config_builder(ClientConfigBuilder);
 }
@@ -97,11 +101,16 @@ impl rustls_client_config_builder {
     /// Create a rustls_client_config_builder. Caller owns the memory and must
     /// eventually call rustls_client_config_builder_build, then free the
     /// resulting rustls_client_config.
-    /// This uses rustls safe default values
-    /// for the cipher suites, key exchange groups and protocol versions.
-    /// This starts out with no trusted roots.
-    /// Caller must add roots with rustls_client_config_builder_load_roots_from_file
-    /// or provide a custom verifier.
+    ///
+    /// Alternatively, if an error occurs or, you don't wish to build a config,
+    /// call `rustls_client_config_builder_free` to free the builder directly.
+    ///
+    /// This uses rustls safe default values for the cipher suites, key exchange
+    /// groups and protocol versions.
+    ///
+    /// This starts out with no trusted roots. Caller must add roots with
+    /// rustls_client_config_builder_load_roots_from_file or provide a custom
+    /// verifier.
     #[no_mangle]
     pub extern "C" fn rustls_client_config_builder_new() -> *mut rustls_client_config_builder {
         ffi_panic_boundary! {
@@ -125,20 +134,26 @@ impl rustls_client_config_builder {
 
     /// Create a rustls_client_config_builder. Caller owns the memory and must
     /// eventually call rustls_client_config_builder_build, then free the
-    /// resulting rustls_client_config. Specify cipher suites in preference
-    /// order; the `cipher_suites` parameter must point to an array containing
-    /// `len` pointers to `rustls_supported_ciphersuite` previously obtained
-    /// from `rustls_all_ciphersuites_get_entry()`, or to a provided array,
-    /// RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES. Set the TLS
-    /// protocol versions to use when negotiating a TLS session.
+    /// resulting rustls_client_config.
+    ///
+    /// Alternatively, if an error occurs or, you don't wish to build a config,
+    /// call `rustls_client_config_builder_free` to free the builder directly.
     ///
+    /// Specify cipher suites in preference order; the `cipher_suites` parameter
+    /// must point to an array containing `cipher_suites_len` pointers to
+    /// `rustls_supported_ciphersuite` previously obtained from
+    /// `rustls_all_ciphersuites_get_entry()`, or to a provided array,
+    /// RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES.
+    ///
+    /// Set the TLS protocol versions to use when negotiating a TLS session.
     /// `tls_version` is the version of the protocol, as defined in rfc8446,
     /// ch. 4.2.1 and end of ch. 5.1. Some values are defined in
     /// `rustls_tls_version` for convenience, and the arrays
     /// RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly.
     ///
-    /// `versions` will only be used during the call and the application retains
-    /// ownership. `len` is the number of consecutive `uint16_t` pointed to by `versions`.
+    /// `tls_versions` will only be used during the call and the application retains
+    /// ownership. `tls_versions_len` is the number of consecutive `uint16_t`
+    /// pointed to by `tls_versions`.
     #[no_mangle]
     pub extern "C" fn rustls_client_config_builder_new_custom(
         cipher_suites: *const *const rustls_supported_ciphersuite,
@@ -244,6 +259,7 @@ struct Verifier {
 /// Safety: Verifier is Send because we don't allocate or deallocate any of its
 /// fields.
 unsafe impl Send for Verifier {}
+
 /// Safety: Verifier is Sync if the C code that passes us a callback that
 /// obeys the concurrency safety requirements documented in
 /// rustls_client_config_builder_dangerous_set_certificate_verifier.

src/rustls.h

@@ -203,9 +203,13 @@ typedef struct rustls_client_config rustls_client_config;
  * A client config being constructed. A builder can be modified by,
  * e.g. rustls_client_config_builder_load_roots_from_file. Once you're
  * done configuring settings, call rustls_client_config_builder_build
- * to turn it into a *rustls_client_config. This object is not safe
- * for concurrent mutation. Under the hood, it corresponds to a
- * `Box<ClientConfig>`.
+ * to turn it into a *rustls_client_config.
+ *
+ * Alternatively, if an error occurs or, you don't wish to build a config,
+ * call `rustls_client_config_builder_free` to free the builder directly.
+ *
+ * This object is not safe for concurrent mutation. Under the hood,
+ * it corresponds to a `Box<ClientConfig>`.
  * <https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html>
  */
 typedef struct rustls_client_config_builder rustls_client_config_builder;
@@ -253,8 +257,10 @@ typedef struct rustls_server_config rustls_server_config;
  * A server config being constructed. A builder can be modified by,
  * e.g. rustls_server_config_builder_load_native_roots. Once you're
  * done configuring settings, call rustls_server_config_builder_build
- * to turn it into a *const rustls_server_config. This object is not safe
- * for concurrent mutation.
+ * to turn it into a *const rustls_server_config. Alternatively, if
+ * an error occurs or, you don't wish to build a config, call
+ * `rustls_server_config_builder_free` to free the builder directly.
+ * This object is not safe for concurrent mutation.
  * <https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html>
  */
 typedef struct rustls_server_config_builder rustls_server_config_builder;
@@ -1272,31 +1278,42 @@ void rustls_server_cert_verifier_free(struct rustls_server_cert_verifier *verifi
  * Create a rustls_client_config_builder. Caller owns the memory and must
  * eventually call rustls_client_config_builder_build, then free the
  * resulting rustls_client_config.
- * This uses rustls safe default values
- * for the cipher suites, key exchange groups and protocol versions.
- * This starts out with no trusted roots.
- * Caller must add roots with rustls_client_config_builder_load_roots_from_file
- * or provide a custom verifier.
+ *
+ * Alternatively, if an error occurs or, you don't wish to build a config,
+ * call `rustls_client_config_builder_free` to free the builder directly.
+ *
+ * This uses rustls safe default values for the cipher suites, key exchange
+ * groups and protocol versions.
+ *
+ * This starts out with no trusted roots. Caller must add roots with
+ * rustls_client_config_builder_load_roots_from_file or provide a custom
+ * verifier.
  */
 struct rustls_client_config_builder *rustls_client_config_builder_new(void);
 
 /**
  * Create a rustls_client_config_builder. Caller owns the memory and must
  * eventually call rustls_client_config_builder_build, then free the
- * resulting rustls_client_config. Specify cipher suites in preference
- * order; the `cipher_suites` parameter must point to an array containing
- * `len` pointers to `rustls_supported_ciphersuite` previously obtained
- * from `rustls_all_ciphersuites_get_entry()`, or to a provided array,
- * RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES. Set the TLS
- * protocol versions to use when negotiating a TLS session.
+ * resulting rustls_client_config.
+ *
+ * Alternatively, if an error occurs or, you don't wish to build a config,
+ * call `rustls_client_config_builder_free` to free the builder directly.
  *
+ * Specify cipher suites in preference order; the `cipher_suites` parameter
+ * must point to an array containing `cipher_suites_len` pointers to
+ * `rustls_supported_ciphersuite` previously obtained from
+ * `rustls_all_ciphersuites_get_entry()`, or to a provided array,
+ * RUSTLS_DEFAULT_CIPHER_SUITES or RUSTLS_ALL_CIPHER_SUITES.
+ *
+ * Set the TLS protocol versions to use when negotiating a TLS session.
  * `tls_version` is the version of the protocol, as defined in rfc8446,
  * ch. 4.2.1 and end of ch. 5.1. Some values are defined in
  * `rustls_tls_version` for convenience, and the arrays
  * RUSTLS_DEFAULT_VERSIONS or RUSTLS_ALL_VERSIONS can be used directly.
  *
- * `versions` will only be used during the call and the application retains
- * ownership. `len` is the number of consecutive `uint16_t` pointed to by `versions`.
+ * `tls_versions` will only be used during the call and the application retains
+ * ownership. `tls_versions_len` is the number of consecutive `uint16_t`
+ * pointed to by `tls_versions`.
  */
 rustls_result rustls_client_config_builder_new_custom(const struct rustls_supported_ciphersuite *const *cipher_suites,
                                                       size_t cipher_suites_len,
@@ -1687,19 +1704,23 @@ struct rustls_str rustls_slice_str_get(const struct rustls_slice_str *input, siz
 /**
  * Create a rustls_server_config_builder. Caller owns the memory and must
  * eventually call rustls_server_config_builder_build, then free the
- * resulting rustls_server_config. This uses rustls safe default values
+ * resulting rustls_server_config. Alternatively, if an error occurs or,
+ * you don't wish to build a config, call `rustls_server_config_builder_free`
+ * to free the builder directly. This uses rustls safe default values
  * for the cipher suites, key exchange groups and protocol versions.
  */
 struct rustls_server_config_builder *rustls_server_config_builder_new(void);
 
 /**
  * Create a rustls_server_config_builder. Caller owns the memory and must
  * eventually call rustls_server_config_builder_build, then free the
- * resulting rustls_server_config. Specify cipher suites in preference
- * order; the `cipher_suites` parameter must point to an array containing
- * `len` pointers to `rustls_supported_ciphersuite` previously obtained
- * from `rustls_all_ciphersuites_get_entry()`. Set the TLS protocol
- * versions to use when negotiating a TLS session.
+ * resulting rustls_server_config. Alternatively, if
+ * an error occurs or, you don't wish to build a config, call
+ * `rustls_server_config_builder_free` to free the builder directly. Specify
+ * cipher suites in preference order; the `cipher_suites` parameter must
+ * point to an array containing `len` pointers to `rustls_supported_ciphersuite`
+ * previously obtained from `rustls_all_ciphersuites_get_entry()`.
+ * Set the TLS protocol versions to use when negotiating a TLS session.
  *
  * `tls_version` is the version of the protocol, as defined in rfc8446,
  * ch. 4.2.1 and end of ch. 5.1. Some values are defined in

src/server.rs

@@ -34,8 +34,10 @@ box_castable! {
     /// A server config being constructed. A builder can be modified by,
     /// e.g. rustls_server_config_builder_load_native_roots. Once you're
     /// done configuring settings, call rustls_server_config_builder_build
-    /// to turn it into a *const rustls_server_config. This object is not safe
-    /// for concurrent mutation.
+    /// to turn it into a *const rustls_server_config. Alternatively, if
+    /// an error occurs or, you don't wish to build a config, call
+    /// `rustls_server_config_builder_free` to free the builder directly.
+    /// This object is not safe for concurrent mutation.
     /// <https://docs.rs/rustls/latest/rustls/struct.ConfigBuilder.html>
     pub struct rustls_server_config_builder(ServerConfigBuilder);
 }
@@ -59,7 +61,9 @@ arc_castable! {
 impl rustls_server_config_builder {
     /// Create a rustls_server_config_builder. Caller owns the memory and must
     /// eventually call rustls_server_config_builder_build, then free the
-    /// resulting rustls_server_config. This uses rustls safe default values
+    /// resulting rustls_server_config. Alternatively, if an error occurs or,
+    /// you don't wish to build a config, call `rustls_server_config_builder_free`
+    /// to free the builder directly. This uses rustls safe default values
     /// for the cipher suites, key exchange groups and protocol versions.
     #[no_mangle]
     pub extern "C" fn rustls_server_config_builder_new() -> *mut rustls_server_config_builder {
@@ -85,11 +89,13 @@ impl rustls_server_config_builder {
 
     /// Create a rustls_server_config_builder. Caller owns the memory and must
     /// eventually call rustls_server_config_builder_build, then free the
-    /// resulting rustls_server_config. Specify cipher suites in preference
-    /// order; the `cipher_suites` parameter must point to an array containing
-    /// `len` pointers to `rustls_supported_ciphersuite` previously obtained
-    /// from `rustls_all_ciphersuites_get_entry()`. Set the TLS protocol
-    /// versions to use when negotiating a TLS session.
+    /// resulting rustls_server_config. Alternatively, if
+    /// an error occurs or, you don't wish to build a config, call
+    /// `rustls_server_config_builder_free` to free the builder directly. Specify
+    /// cipher suites in preference order; the `cipher_suites` parameter must
+    /// point to an array containing `len` pointers to `rustls_supported_ciphersuite`
+    /// previously obtained from `rustls_all_ciphersuites_get_entry()`.
+    /// Set the TLS protocol versions to use when negotiating a TLS session.
     ///
     /// `tls_version` is the version of the protocol, as defined in rfc8446,
     /// ch. 4.2.1 and end of ch. 5.1. Some values are defined in
@@ -524,6 +530,7 @@ impl ResolvesServerCert for ClientHelloResolver {
 /// as the registered callbacks are thread safe. This is
 /// documented as a requirement in the API.
 unsafe impl Sync for ClientHelloResolver {}
+
 unsafe impl Send for ClientHelloResolver {}
 
 impl Debug for ClientHelloResolver {