docs: 为 config.c、log.c、tls.c 添加函数级 Doxygen 注释

- config.c: 为 JSON 解析器内部函数和公共 API 添加完整注释
- log.c: 为日志级别转换和输出函数添加注释
- tls.c: 为 TLS 连接管理、Memory BIO 操作和 ALPN 回调添加注释
- http2.c: 移除过时的 TODO 占位注释（请求体收集已实现）

config.c

@@ -51,6 +51,13 @@ typedef struct {
 
 /* === 内部：parser 辅助函数 === */
 
+/**
+ * parser_init - 初始化 JSON 解析器
+ *
+ * @param p 解析器状态结构
+ * @param src JSON 源字符串
+ * @param len 源字符串长度
+ */
 static void parser_init(parser_t *p, const char *src, size_t len) {
     p->src = src;
     p->pos = 0;
@@ -58,6 +65,13 @@ static void parser_init(parser_t *p, const char *src, size_t len) {
     p->line = 1;
 }
 
+/**
+ * parser_skip_ws - 跳过空白字符和注释
+ *
+ * 支持空格、制表符、换行，以及 // 行注释。
+ *
+ * @param p 解析器状态结构
+ */
 static void parser_skip_ws(parser_t *p) {
     while (p->pos < p->len) {
         char c = p->src[p->pos];
@@ -76,6 +90,15 @@ static void parser_skip_ws(parser_t *p) {
     }
 }
 
+/**
+ * parser_next_token - 读取下一个 JSON token
+ *
+ * 支持的 token 类型：字符串、数字、true、false、
+ * 以及各种分隔符（{ } [ ] , :）。
+ *
+ * @param p 解析器状态结构
+ * @return 下一个 token
+ */
 static token_t parser_next_token(parser_t *p) {
     parser_skip_ws(p);
     token_t t = {TOKEN_INVALID, NULL, 0, p->line};
@@ -139,12 +162,26 @@ static token_t parser_next_token(parser_t *p) {
     }
 }
 
+/**
+ * token_expect - 期望下一个 token 为指定类型
+ *
+ * @param p 解析器状态结构
+ * @param expected 期望的 token 类型
+ * @return true 匹配，false 不匹配
+ */
 static bool token_expect(parser_t *p, token_type_t expected) {
     token_t t = parser_next_token(p);
     return t.type == expected;
 }
 
-/* 复制 token 内容为 C 字符串（处理转义） */
+/**
+ * token_str_dup - 将字符串 token 复制为 C 字符串
+ *
+ * 处理 JSON 字符串中的转义序列（\n \t \r \\ \"）。
+ *
+ * @param t 字符串 token
+ * @return 新分配的 C 字符串，调用者负责释放；失败返回 NULL
+ */
 static char *token_str_dup(const token_t *t) {
     char *buf = (char *)malloc(t->len + 1);
     if (!buf) return NULL;
@@ -169,6 +206,12 @@ static char *token_str_dup(const token_t *t) {
     return buf;
 }
 
+/**
+ * token_to_long - 将数字 token 转换为长整型
+ *
+ * @param t 数字 token
+ * @return 转换后的数值
+ */
 static long token_to_long(const token_t *t) {
     char buf[32] = {0};
     size_t n = t->len < 31 ? t->len : 31;
@@ -176,6 +219,12 @@ static long token_to_long(const token_t *t) {
     return strtol(buf, NULL, 10);
 }
 
+/**
+ * str_to_log_level - 将字符串转换为日志级别
+ *
+ * @param str 日志级别字符串（error/warn/info/debug）
+ * @return 对应的日志级别枚举值，无效时返回 LOG_LEVEL_INFO
+ */
 static log_level_t str_to_log_level(const char *str) {
     if (strcmp(str, "error") == 0) return LOG_LEVEL_ERROR;
     if (strcmp(str, "warn") == 0) return LOG_LEVEL_WARN;
@@ -186,6 +235,21 @@ static log_level_t str_to_log_level(const char *str) {
 
 /* === 公共 API === */
 
+/**
+ * config_load_from_file - 从 JSON 配置文件加载配置
+ *
+ * 解析 cocoon.json 格式，支持以下字段：
+ *   root_dir, port, threaded, num_workers, max_connections, timeout_ms,
+ *   log_level, gzip_enabled, brotli_enabled, tls_cert, tls_key, tls_enabled,
+ *   access_log, cors_enabled, auth_user, auth_pass, rate_limit,
+ *   plugins（字符串或数组）, proxies（对象数组）
+ *
+ * 未知字段将被静默忽略，便于向后兼容。
+ *
+ * @param path 配置文件路径
+ * @param config 输出配置结构体
+ * @return true 成功，false 失败（会输出错误信息到 stderr）
+ */
 bool config_load_from_file(const char *path, cocoon_config_t *config) {
     if (!path || !config) return false;
 
@@ -423,6 +487,32 @@ bool config_load_from_file(const char *path, cocoon_config_t *config) {
     return true;
 }
 
+/**
+ * config_merge - 将命令行参数合并到基础配置
+ *
+ * 命令行显式指定的值覆盖配置文件中的值。
+ * 对于字符串字段，会释放旧值并复制新值。
+ *
+ * @param base 基础配置（通常来自配置文件）
+ * @param cmdline 命令行配置
+ * @param has_root_dir  是否显式指定 root_dir
+ * @param has_port      是否显式指定 port
+ * @param has_workers   是否显式指定 num_workers
+ * @param has_max_conn  是否显式指定 max_connections
+ * @param has_timeout   是否显式指定 timeout_ms
+ * @param has_log_level 是否显式指定 log_level
+ * @param has_gzip_enabled    是否显式指定 gzip_enabled
+ * @param has_brotli_enabled  是否显式指定 brotli_enabled
+ * @param has_tls_cert  是否显式指定 tls_cert
+ * @param has_tls_key   是否显式指定 tls_key
+ * @param has_tls_enabled 是否显式指定 tls_enabled
+ * @param has_access_log 是否显式指定 access_log
+ * @param has_cors_enabled 是否显式指定 cors_enabled
+ * @param has_auth_user 是否显式指定 auth_user
+ * @param has_auth_pass 是否显式指定 auth_pass
+ * @param has_rate_limit 是否显式指定 rate_limit
+ * @param has_plugins   是否显式指定 plugins
+ */
 void config_merge(cocoon_config_t *base, const cocoon_config_t *cmdline,
                   bool has_root_dir, bool has_port, bool has_workers,
                   bool has_max_conn, bool has_timeout, bool has_log_level,

http2.c

@@ -689,7 +689,7 @@ static int on_stream_close_callback(nghttp2_session *session __attribute__((unus
 /**
  * on_data_chunk_recv_callback - DATA 帧数据块接收回调
  *
- * 目前为占位实现，TODO：将请求体数据追加到流缓冲区。
+ * 将请求体数据追加到流缓冲区。支持 Content-Length 和分块传输。
  *
  * @param session nghttp2 会话（未使用）
  * @param flags 标志（未使用）

log.c

@@ -13,6 +13,12 @@
 static log_level_t g_level = LOG_LEVEL_INFO;
 static const char *g_prefix = "[Cocoon]";
 
+/**
+ * level_str - 将日志级别转换为字符串
+ *
+ * @param level 日志级别
+ * @return 级别名称（ERROR/WARN/INFO/DEBUG/UNKNOWN）
+ */
 static const char *level_str(log_level_t level) {
     switch (level) {
         case LOG_LEVEL_ERROR: return "ERROR";
@@ -23,18 +29,45 @@ static const char *level_str(log_level_t level) {
     }
 }
 
+/**
+ * log_set_level - 设置全局日志级别
+ *
+ * 低于此级别的日志消息将被忽略。
+ *
+ * @param level 日志级别
+ */
 void log_set_level(log_level_t level) {
     g_level = level;
 }
 
+/**
+ * log_set_prefix - 设置日志前缀
+ *
+ * @param prefix 前缀字符串，设为 NULL 则无前缀
+ */
 void log_set_prefix(const char *prefix) {
     g_prefix = prefix;
 }
 
+/**
+ * log_get_level - 获取当前日志级别
+ *
+ * @return 当前日志级别
+ */
 log_level_t log_get_level(void) {
     return g_level;
 }
 
+/**
+ * log_output - 日志输出核心函数
+ *
+ * 格式化时间戳、前缀、级别和消息，输出到 stderr。
+ * 若日志级别低于全局级别则直接返回。
+ *
+ * @param level 日志级别
+ * @param fmt 格式字符串
+ * @param args 可变参数列表
+ */
 static void log_output(log_level_t level, const char *fmt, va_list args) {
     if (level > g_level) return;
 
@@ -52,6 +85,10 @@ static void log_output(log_level_t level, const char *fmt, va_list args) {
     fprintf(stderr, "\n");
 }
 
+/**
+ * log_error - 输出 ERROR 级别日志
+ * @param fmt 格式字符串
+ */
 void log_error(const char *fmt, ...) {
     va_list args;
     va_start(args, fmt);
@@ -59,6 +96,10 @@ void log_error(const char *fmt, ...) {
     va_end(args);
 }
 
+/**
+ * log_warn - 输出 WARN 级别日志
+ * @param fmt 格式字符串
+ */
 void log_warn(const char *fmt, ...) {
     va_list args;
     va_start(args, fmt);
@@ -66,6 +107,10 @@ void log_warn(const char *fmt, ...) {
     va_end(args);
 }
 
+/**
+ * log_info - 输出 INFO 级别日志
+ * @param fmt 格式字符串
+ */
 void log_info(const char *fmt, ...) {
     va_list args;
     va_start(args, fmt);
@@ -73,6 +118,10 @@ void log_info(const char *fmt, ...) {
     va_end(args);
 }
 
+/**
+ * log_debug - 输出 DEBUG 级别日志
+ * @param fmt 格式字符串
+ */
 void log_debug(const char *fmt, ...) {
     va_list args;
     va_start(args, fmt);

tls.c

@@ -33,12 +33,27 @@ static tls_conn_t **g_map = NULL;
 static int g_map_cap = 0;
 static SSL_CTX *g_ctx = NULL;
 
-/* 内部：O(1) fd 查表 */
+/**
+ * tls_lookup - 根据 fd 查找 TLS 连接
+ *
+ * O(1) 查表，使用动态数组索引。
+ *
+ * @param fd socket 文件描述符
+ * @return TLS 连接结构，未找到返回 NULL
+ */
 static tls_conn_t* tls_lookup(int fd) {
     if (fd >= 0 && fd < g_map_cap) return g_map[fd];
     return NULL;
 }
 
+/**
+ * tls_map_set - 将 fd 与 TLS 连接关联
+ *
+ * 若数组容量不足则自动扩容。
+ *
+ * @param fd socket 文件描述符
+ * @param t TLS 连接结构
+ */
 static void tls_map_set(int fd, tls_conn_t *t) {
     if (fd >= g_map_cap) {
         int old_cap = g_map_cap;
@@ -49,11 +64,25 @@ static void tls_map_set(int fd, tls_conn_t *t) {
     g_map[fd] = t;
 }
 
+/**
+ * tls_map_clear - 清除 fd 与 TLS 连接的关联
+ *
+ * @param fd socket 文件描述符
+ */
 static void tls_map_clear(int fd) {
     if (fd >= 0 && fd < g_map_cap) g_map[fd] = NULL;
 }
 
-/* 内部：从 socket 读取原始数据（协程感知） */
+/**
+ * socket_read - 从 socket 读取原始数据（协程感知）
+ *
+ * 若当前在协程调度器中则使用 coco_read，否则使用标准 read。
+ *
+ * @param fd socket 文件描述符
+ * @param buf 读取缓冲区
+ * @param len 最大读取长度
+ * @return 实际读取字节数，失败返回 -1
+ */
 static ssize_t socket_read(int fd, void *buf, size_t len) {
     if (coco_sched_get_current() != NULL) {
         return coco_read(fd, buf, len);
@@ -61,7 +90,16 @@ static ssize_t socket_read(int fd, void *buf, size_t len) {
     return read(fd, buf, len);
 }
 
-/* 内部：向 socket 写入原始数据 */
+/**
+ * socket_write_all - 向 socket 写入全部数据（协程感知）
+ *
+ * 循环写入直至全部数据发送完毕。若当前在协程调度器中则使用 coco_write。
+ *
+ * @param fd socket 文件描述符
+ * @param buf 数据缓冲区
+ * @param len 数据长度
+ * @return 实际发送字节数，失败返回 -1
+ */
 static ssize_t socket_write_all(int fd, const void *buf, size_t len) {
     if (coco_sched_get_current() != NULL) {
         size_t sent = 0;
@@ -94,7 +132,13 @@ static ssize_t socket_write_all(int fd, const void *buf, size_t len) {
     }
 }
 
-/* 内部：将 write BIO 中的加密数据刷到 socket */
+/**
+ * flush_wbio - 将 write BIO 中的加密数据刷到 socket
+ *
+ * @param fd socket 文件描述符
+ * @param wbio write BIO
+ * @return 0 成功，-1 失败
+ */
 static int flush_wbio(int fd, BIO *wbio) {
     char buf[16384];
     int pending = BIO_read(wbio, buf, sizeof(buf));
@@ -105,7 +149,19 @@ static int flush_wbio(int fd, BIO *wbio) {
     return 0;
 }
 
-/* 内部：ALPN 选择回调，优先选择 h2，否则 http/1.1 */
+/**
+ * tls_alpn_select_cb - ALPN 协议选择回调
+ *
+ * 优先选择 h2（HTTP/2），次选 http/1.1。
+ *
+ * @param ssl SSL 对象（未使用）
+ * @param out 输出选中的协议
+ * @param outlen 输出协议长度
+ * @param in 客户端 ALPN 列表
+ * @param inlen 客户端 ALPN 列表长度
+ * @param arg 用户参数（未使用）
+ * @return SSL_TLSEXT_ERR_OK 成功，SSL_TLSEXT_ERR_NOACK 无匹配
+ */
 static int tls_alpn_select_cb(SSL *ssl __attribute__((unused)), const unsigned char **out,
                                unsigned char *outlen, const unsigned char *in,
                                unsigned int inlen, void *arg __attribute__((unused))) {
@@ -146,6 +202,16 @@ static int tls_alpn_select_cb(SSL *ssl __attribute__((unused)), const unsigned c
 
 /* ===== 公共 API ===== */
 
+/**
+ * tls_create_context - 创建 TLS 服务器上下文
+ *
+ * 初始化 OpenSSL，加载证书和私钥，设置 ALPN 回调。
+ * 最低支持 TLS 1.2。
+ *
+ * @param cert_path 证书文件路径（PEM 格式）
+ * @param key_path 私钥文件路径（PEM 格式）
+ * @return 0 成功，-1 失败
+ */
 int tls_create_context(const char *cert_path, const char *key_path) {
     if (!cert_path || !key_path) return -1;
 
@@ -193,6 +259,11 @@ int tls_create_context(const char *cert_path, const char *key_path) {
     return 0;
 }
 
+/**
+ * tls_destroy_context - 销毁 TLS 上下文并清理所有连接
+ *
+ * 释放 SSL_CTX、所有 TLS 连接映射表项及其关联资源。
+ */
 void tls_destroy_context(void) {
     if (g_ctx) {
         SSL_CTX_free(g_ctx);
@@ -213,10 +284,24 @@ void tls_destroy_context(void) {
     }
 }
 
+/**
+ * tls_has_context - 检查是否已创建 TLS 上下文
+ *
+ * @return true 已创建，false 未创建
+ */
 bool tls_has_context(void) {
     return g_ctx != NULL;
 }
 
+/**
+ * tls_accept - 接受新 TLS 连接并执行握手
+ *
+ * 为指定 fd 创建 TLS 连接对象，执行完整的握手循环。
+ * 使用 Memory BIO 与协程 I/O 集成。
+ *
+ * @param fd socket 文件描述符
+ * @return 0 成功，-1 失败
+ */
 int tls_accept(int fd) {
     if (!g_ctx) return -1;
 
@@ -287,6 +372,16 @@ fail:
     return -1;
 }
 
+/**
+ * tls_read - 从 TLS 连接读取解密数据
+ *
+ * 若 SSL 缓冲区为空，则从 socket 读取加密数据并解密。
+ *
+ * @param fd socket 文件描述符
+ * @param buf 读取缓冲区
+ * @param len 最大读取长度
+ * @return 实际读取字节数，0 对端关闭，-1 错误
+ */
 ssize_t tls_read(int fd, void *buf, size_t len) {
     tls_conn_t *t = tls_lookup(fd);
     if (!t || !t->ssl) return -1;
@@ -315,6 +410,16 @@ ssize_t tls_read(int fd, void *buf, size_t len) {
     }
 }
 
+/**
+ * tls_write - 向 TLS 连接写入数据
+ *
+ * 数据经 SSL 加密后通过 socket 发送。
+ *
+ * @param fd socket 文件描述符
+ * @param buf 数据缓冲区
+ * @param len 数据长度
+ * @return 实际发送字节数，-1 错误
+ */
 ssize_t tls_write(int fd, const void *buf, size_t len) {
     tls_conn_t *t = tls_lookup(fd);
     if (!t || !t->ssl) return -1;
@@ -346,6 +451,13 @@ ssize_t tls_write(int fd, const void *buf, size_t len) {
     return (ssize_t)total;
 }
 
+/**
+ * tls_close - 关闭 TLS 连接并释放资源
+ *
+ * 发送 close_notify，释放 SSL 对象和连接映射。
+ *
+ * @param fd socket 文件描述符
+ */
 void tls_close(int fd) {
     tls_conn_t *t = tls_lookup(fd);
     if (!t) return;
@@ -362,10 +474,22 @@ void tls_close(int fd) {
     free(t);
 }
 
+/**
+ * tls_has_connection - 检查 fd 是否有关联的 TLS 连接
+ *
+ * @param fd socket 文件描述符
+ * @return true 有 TLS 连接，false 无
+ */
 bool tls_has_connection(int fd) {
     return tls_lookup(fd) != NULL;
 }
 
+/**
+ * tls_negotiated_http2 - 检查 ALPN 协商结果是否为 HTTP/2
+ *
+ * @param fd socket 文件描述符
+ * @return true 协商为 h2，false 未协商或为 http/1.1
+ */
 bool tls_negotiated_http2(int fd) {
     tls_conn_t *t = tls_lookup(fd);
     if (!t || !t->ssl) return false;