Docs for tls.h and trace.h.

src/tls.h

@@ -9,9 +9,19 @@
 #include <stdbool.h>
 #include <stddef.h>
 
+/**
+** A TLS context.  May have many tf_tls_session_t instances.
+*/
 typedef struct _tf_tls_context_t tf_tls_context_t;
+
+/**
+** A TLS session.  Belongs to one tf_tls_context_t and represents a single connection.
+*/
 typedef struct _tf_tls_session_t tf_tls_session_t;
 
+/**
+** The state of a TLS handshake.
+*/
 typedef enum _tf_tls_handshake_t
 {
 	k_tls_handshake_done,
@@ -19,31 +29,149 @@ typedef enum _tf_tls_handshake_t
 	k_tls_handshake_failed,
 } tf_tls_handshake_t;
 
+/**
+** Possible error statuses from tf_tls_session_read_plain.
+*/
 typedef enum _tf_tls_read_t
 {
 	k_tls_read_zero = -1,
 	k_tls_read_failed = -2,
 } tf_tls_read_t;
 
+/**
+** Create a TLS context.  Clean up with tf_tls_context_destroy().
+** @return A new TLS context.
+*/
 tf_tls_context_t* tf_tls_context_create();
+
+/**
+** Set the TLS context's server certificate.
+** @param context The TLS context.
+** @param certificate The certificate in PEM format.
+** @return true if set successfully.
+*/
 bool tf_tls_context_set_certificate(tf_tls_context_t* context, const char* certificate);
+
+/**
+** Set the TLS context's server certificate's private key.
+** @param context The TLS context.
+** @param private_key The private key in PEM format.
+** @return true if set successfully.
+*/
 bool tf_tls_context_set_private_key(tf_tls_context_t* context, const char* private_key);
+
+/**
+** Add a trusted certificate.
+** @param context The TLS context.
+** @param certificate The certificate in PEM format.
+** @return true if the certificate was added to the trusted list successfully.
+*/
 bool tf_tls_context_add_trusted_certificate(tf_tls_context_t* context, const char* certificate);
+
+/**
+** Create a TLS session from a context.  Once created, call
+** tf_tls_session_handshake() until it returns k_tls_handshake_done.  Call
+** tf_tls_session_[read/write]_[plain/encrypted]() as data is available.
+** @param context The TLS context.  Clean up with tf_tls_session_destroy().
+** @return A new TLS session.
+*/
 tf_tls_session_t* tf_tls_context_create_session(tf_tls_context_t* context);
+
+/**
+** Destroy a TLS context.
+** @param context The TLS contextx created by tf_tls_context_create().
+*/
 void tf_tls_context_destroy(tf_tls_context_t* context);
 
+/**
+** Destroy a TLS session.
+** @param session A TLS sesssion created by tf_tls_context_create_session().
+*/
 void tf_tls_session_destroy(tf_tls_session_t* session);
+
+/**
+** Set the remote hostname for a session.
+** @param session The TLS session.
+** @param hostname The hostname.
+*/
 void tf_tls_session_set_hostname(tf_tls_session_t* session, const char* hostname);
+
+/**
+** Begin an outgoing TLS session.
+** @param session The TLS session.
+*/
 void tf_tls_session_start_accept(tf_tls_session_t* session);
+
+/**
+** Begin an incoming TLS session.
+** @param session The TLS session.
+*/
 void tf_tls_session_start_connect(tf_tls_session_t* session);
+
+/**
+** Begin the clean shutdown process for a TLS session.
+** @param session The TLS session.
+*/
 void tf_tls_session_shutdown(tf_tls_session_t* session);
+
+/**
+** Get the certificate from the remote end of a TLS session if available.
+** @param session The TLS session.
+** @param buffer A buffer to receive the certificate.
+** @param bytes The size of the buffer.
+** @return The size of the returned certificate, or -1 on failure.
+*/
 int tf_tls_session_get_peer_certificate(tf_tls_session_t* session, char* buffer, size_t bytes);
+
+/**
+** Update the TLS handshake.  Call repeatedly as new data is available until it returns done.
+** @param session The TLS session.
+** @return The current state of the handshake process.
+*/
 tf_tls_handshake_t tf_tls_session_handshake(tf_tls_session_t* session);
 
+/**
+** Read decrypted data from the TLS session.
+** @param session The TLS session.
+** @param buffer A buffer to receive the data.
+** @param bytes The size of the buffer.
+** @return The number of bytes returned.
+*/
 int tf_tls_session_read_plain(tf_tls_session_t* session, char* buffer, size_t bytes);
+
+/**
+** Write unencrypted data to the TLS session.
+** @param session The TLS session.
+** @param buffer The data to encrypt.
+** @param bytes The size of the data.
+** @return 1 on success, 0 on failure.
+*/
 int tf_tls_session_write_plain(tf_tls_session_t* session, const char* buffer, size_t bytes);
+
+/**
+** Read encrypted data from the TLS session that needs to be sent.
+** @param session The TLS session.
+** @param buffer A buffer to receive the data.
+** @param bytes The size of the buffer.
+** @return The number of bytes returned.
+*/
 int tf_tls_session_read_encrypted(tf_tls_session_t* session, char* buffer, size_t bytes);
+
+/**
+** Write encrypted data to the TLS session.
+** @param session The TLS session.
+** @param buffer The encrypted data.
+** @param bytes The number of bytes written.
+*/
 int tf_tls_session_write_encrypted(tf_tls_session_t* session, const char* buffer, size_t bytes);
+
+/**
+** Retrieve the last error from a TLS session.
+** @param session The TLS session.
+** @param buffer A buffer to receive the error text.
+** @param bytes The size of the buffer.
+** @return true if an error was retrieved.
+*/
 bool tf_tls_session_get_error(tf_tls_session_t* session, char* buffer, size_t bytes);
 
 /** @} */

src/trace.h

@@ -3,32 +3,103 @@
 /**
 ** \defgroup trace Performance Tracing
 ** Generates trace output that is compatible with speedscope.app,
-** chrome://tracing or ui.perfetto.dev for scrutining what each thread is doing
-** for optimization purposes.
+** chrome://tracing or ui.perfetto.dev for scrutinizing what each thread is
+** doing for optimization purposes.
 ** @{
 */
 
 #include <inttypes.h>
 #include <stddef.h>
 
+/**
+** A trace instance.
+*/
 typedef struct _tf_trace_t tf_trace_t;
+
+/**
+** An SQLite database instance.
+*/
 typedef struct sqlite3 sqlite3;
 
+/**
+** Create a trace instance.  Can be used to produce a Chrome trace event
+** document for analyzing performance.  Clean up with tf_trace_destroy().
+** @return A trace instance.
+*/
 tf_trace_t* tf_trace_create();
+
+/**
+** Destroy a trace instance that was created with tf_trace_create().
+*/
 void tf_trace_destroy(tf_trace_t* trace);
 
+/**
+** Set the name of the current process.
+** @param trace The trace instance.
+** @param name The name of the process.
+*/
 void tf_trace_set_process_name(tf_trace_t* trace, const char* name);
 
+/**
+** Record counter values.
+** @param trace The trace instance.
+** @param name The counter group name.
+** @param argc The number of counters.
+** @param arg_names The counter names.
+** @param arg_values The counter values.
+*/
 void tf_trace_counter(tf_trace_t* trace, const char* name, int argc, const char** arg_names, const int64_t* arg_values);
+
+/**
+** Begin tracing a time interval.  End with tf_trace_end().
+** @param trace The trace instance.
+** @param name The interval name.
+*/
 void tf_trace_begin(tf_trace_t* trace, const char* name);
+
+/**
+** End tracing the next time interval previously started with tf_trace_begin().
+** @param trace The trace instance.
+*/
 void tf_trace_end(tf_trace_t* trace);
 
+/**
+** Export all currently stored trace data to a string.
+** @param trace The trace instance.
+** @return A string representation of the trace data.
+*/
 char* tf_trace_export(tf_trace_t* trace);
 
+/**
+** A callback to collect trace data.
+** @param trace The trace instance.
+** @param buffer The trace data.
+** @param size The size of the trace data.
+** @param user_data User data registered with the callback.
+*/
 typedef void(tf_trace_write_callback_t)(tf_trace_t* trace, const char* buffer, size_t size, void* user_data);
+
+/**
+** Replace the trace recording behavior.
+** @param trace The trace instance.
+** @param callback A callback that will be called instead of collecting the trace data in a buffer.
+** @param user_data User data to pass to the callback.
+*/
 void tf_trace_set_write_callback(tf_trace_t* trace, tf_trace_write_callback_t* callback, void* user_data);
+
+/**
+** Inject raw trace data.
+** @param trace The trace instance.
+** @param buffer The trace data.
+** @param size The size of the trace data.
+*/
 void tf_trace_raw(tf_trace_t* trace, const char* buffer, size_t size);
 
+/**
+** Register for trace-worthy events from sqlite and record them going forward.
+** @param trace The trace instance.
+** @param sqlite The SQLite database.
+*/
 void tf_trace_sqlite(tf_trace_t* trace, sqlite3* sqlite);
 
 /** @} */