librustls: add missing API docs

A few elements of our public API had no associated docs. This is going
to be flagged as an error by the API doc generation tooling, so let's
fix it up-front with some short doc additions.

librustls/src/client.rs

@@ -570,6 +570,7 @@ pub struct rustls_verify_server_cert_params<'a> {
 #[allow(non_camel_case_types)]
 pub type rustls_verify_server_cert_user_data = *mut libc::c_void;
 
+/// A callback that is invoked to verify a server certificate.
 // According to the nomicon https://doc.rust-lang.org/nomicon/ffi.html#the-nullable-pointer-optimization):
 // > Option<extern "C" fn(c_int) -> c_int> is a correct way to represent a
 // > nullable function pointer using the C ABI (corresponding to the C type int (*)(int)).

librustls/src/connection.rs

@@ -93,6 +93,7 @@ impl std::ops::DerefMut for Connection {
 }
 
 box_castable! {
+    /// A C representation of a Rustls `Connection`.
     pub struct rustls_connection(Connection);
 }
 
@@ -288,6 +289,7 @@ impl rustls_connection {
         }
     }
 
+    /// Returns a `rustls_handshake_kind` describing the `rustls_connection`.
     #[no_mangle]
     pub extern "C" fn rustls_connection_handshake_kind(
         conn: *const rustls_connection,

librustls/src/error.rs

@@ -46,6 +46,7 @@ macro_rules! u32_enum_builder {
 }
 
 u32_enum_builder! {
+    /// Numeric error codes returned from rustls-ffi API functions.
     EnumName: rustls_result;
     EnumDefault: InvalidParameter;
     EnumVal{
@@ -242,6 +243,7 @@ impl rustls_result {
         }
     }
 
+    /// Returns true if the `result` is a certificate related error.
     #[no_mangle]
     pub extern "C" fn rustls_result_is_cert_error(result: c_uint) -> bool {
         use rustls_result::*;

librustls/src/log.rs

@@ -42,6 +42,10 @@ pub(crate) fn ensure_log_registered() {
     log::set_max_level(log::LevelFilter::Debug)
 }
 
+/// Numeric representation of a log level.
+///
+/// Passed as a field of the `rustls_log_params` passed to a log callback.
+/// Use with `rustls_log_level_str` to convert to a string label.
 pub type rustls_log_level = usize;
 
 /// Return a rustls_str containing the stringified version of a log level.
@@ -58,12 +62,16 @@ pub extern "C" fn rustls_log_level_str(level: rustls_log_level) -> rustls_str<'s
     rustls_str::from_str_unchecked(s)
 }
 
+/// Parameter structure passed to a `rustls_log_callback`.
 #[repr(C)]
 pub struct rustls_log_params<'a> {
+    /// The log level the message was logged at.
     pub level: rustls_log_level,
+    /// The message that was logged.
     pub message: rustls_str<'a>,
 }
 
+/// A callback that is invoked for messages logged by rustls.
 #[allow(non_camel_case_types)]
 pub type rustls_log_callback =
     Option<unsafe extern "C" fn(userdata: *mut c_void, params: *const rustls_log_params)>;

librustls/src/rustls.h

@@ -42,6 +42,9 @@ typedef enum rustls_handshake_kind {
   RUSTLS_HANDSHAKE_KIND_RESUMED = 3,
 } rustls_handshake_kind;
 
+/**
+ * Numeric error codes returned from rustls-ffi API functions.
+ */
 enum rustls_result {
   RUSTLS_RESULT_OK = 7000,
   RUSTLS_RESULT_IO = 7001,
@@ -272,6 +275,9 @@ typedef struct rustls_client_config rustls_client_config;
  */
 typedef struct rustls_client_config_builder rustls_client_config_builder;
 
+/**
+ * A C representation of a Rustls `Connection`.
+ */
 typedef struct rustls_connection rustls_connection;
 
 /**
@@ -550,6 +556,9 @@ typedef struct rustls_verify_server_cert_params {
   struct rustls_slice_bytes ocsp_response;
 } rustls_verify_server_cert_params;
 
+/**
+ * A callback that is invoked to verify a server certificate.
+ */
 typedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata,
                                                        const struct rustls_verify_server_cert_params *params);
 
@@ -575,13 +584,31 @@ typedef void (*rustls_keylog_log_callback)(struct rustls_str label,
  */
 typedef int (*rustls_keylog_will_log_callback)(struct rustls_str label);
 
+/**
+ * Numeric representation of a log level.
+ *
+ * Passed as a field of the `rustls_log_params` passed to a log callback.
+ * Use with `rustls_log_level_str` to convert to a string label.
+ */
 typedef size_t rustls_log_level;
 
+/**
+ * Parameter structure passed to a `rustls_log_callback`.
+ */
 typedef struct rustls_log_params {
+  /**
+   * The log level the message was logged at.
+   */
   rustls_log_level level;
+  /**
+   * The message that was logged.
+   */
   struct rustls_str message;
 } rustls_log_params;
 
+/**
+ * A callback that is invoked for messages logged by rustls.
+ */
 typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params);
 
 /**
@@ -1666,6 +1693,9 @@ bool rustls_connection_wants_write(const struct rustls_connection *conn);
  */
 bool rustls_connection_is_handshaking(const struct rustls_connection *conn);
 
+/**
+ * Returns a `rustls_handshake_kind` describing the `rustls_connection`.
+ */
 enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_connection *conn);
 
 /**
@@ -2128,6 +2158,9 @@ struct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind);
  */
 void rustls_error(unsigned int result, char *buf, size_t len, size_t *out_n);
 
+/**
+ * Returns true if the `result` is a certificate related error.
+ */
 bool rustls_result_is_cert_error(unsigned int result);
 
 /**