Add document comments

include/common/file_system.h

@@ -1,6 +1,8 @@
 /**
+ * Copyright 2024 atframework
  * @file file_system.h
- * @brief 文件系统统一接口
+ * @note 文件系统统一接口，主要针对跨平台（Windows,Linux,macOS等）提供尽可能统一且行为一致的接口
+ * @note 允许混合使用 "/" 或 "\" 作为路径分隔符，支持Mingw、Cygwin
  * Licensed under the MIT licenses.
  *
  * @version 1.0
@@ -12,8 +14,8 @@
  *
  */
 
-#ifndef _UTIL_COMMON__FILESYSTEM_H
-#define _UTIL_COMMON__FILESYSTEM_H
+#ifndef UTIL_COMMON__FILESYSTEM_H
+#define UTIL_COMMON__FILESYSTEM_H
 
 #pragma once
 
@@ -254,4 +256,4 @@ class file_system {
 };
 ATFRAMEWORK_UTILS_NAMESPACE_END
 
-#endif  //_UTIL_COMMON__FILESYSTEM_H
+#endif  // UTIL_COMMON__FILESYSTEM_H

src/algorithm/crypto_cipher.cpp

@@ -824,6 +824,7 @@ ATFRAMEWORK_UTILS_API int cipher::encrypt(const unsigned char *input, size_t ile
       defined(ATFRAMEWORK_UTILS_CRYPTO_USE_BORINGSSL)
       int outl, finish_olen;
 
+      // OpenSSL接入采用新的EVP接口
       if (!iv_.empty()) {
         if (!EVP_CipherInit_ex(cipher_context_.enc, nullptr, nullptr, nullptr, &iv_[0], -1)) {
           return details::setup_errorno(*this, static_cast<int64_t>(ERR_peek_error()),
@@ -874,6 +875,7 @@ ATFRAMEWORK_UTILS_API int cipher::encrypt(const unsigned char *input, size_t ile
     }
 
 #  if defined(ATFRAMEWORK_UTILS_CRYPTO_USE_LIBSODIUM) && ATFRAMEWORK_UTILS_CRYPTO_USE_LIBSODIUM
+    // CHACHA20系算法使用 libsodium 接入
     case EN_CIMT_LIBSODIUM_CHACHA20:
       if ((last_errorno_ = crypto_stream_chacha20_xor_ic(output, input, ilen, &iv_[LIBSODIUM_COUNTER_SIZE],
                                                          static_cast<uint64_t>(libsodium_get_counter(&iv_[0])),
@@ -955,6 +957,7 @@ ATFRAMEWORK_UTILS_API int cipher::decrypt(const unsigned char *input, size_t ile
 
 #  if defined(ATFRAMEWORK_UTILS_CRYPTO_USE_OPENSSL) || defined(ATFRAMEWORK_UTILS_CRYPTO_USE_LIBRESSL) || \
       defined(ATFRAMEWORK_UTILS_CRYPTO_USE_BORINGSSL)
+      // OpenSSL接入采用新的EVP接口
       int outl, finish_olen;
 
       if (!iv_.empty()) {
@@ -1007,6 +1010,7 @@ ATFRAMEWORK_UTILS_API int cipher::decrypt(const unsigned char *input, size_t ile
     }
 
 #  if defined(ATFRAMEWORK_UTILS_CRYPTO_USE_LIBSODIUM) && ATFRAMEWORK_UTILS_CRYPTO_USE_LIBSODIUM
+    // CHACHA20系算法使用 libsodium 接入
     case EN_CIMT_LIBSODIUM_CHACHA20:
       if ((last_errorno_ = crypto_stream_chacha20_xor_ic(output, input, ilen, &iv_[LIBSODIUM_COUNTER_SIZE],
                                                          static_cast<uint64_t>(libsodium_get_counter(&iv_[0])),

src/common/file_system.cpp

@@ -350,6 +350,7 @@ ATFRAMEWORK_UTILS_API FILE *file_system::open_tmp_file() {
 ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inout) {
 #if (defined(ATFRAMEWORK_UTILS_ENABLE_WINDOWS_MKTEMP) && ATFRAMEWORK_UTILS_ENABLE_WINDOWS_MKTEMP) || \
     (defined(ATFRAMEWORK_UTILS_ENABLE_POSIX_MKSTEMP) && ATFRAMEWORK_UTILS_ENABLE_POSIX_MKSTEMP)
+  // 适配环境变量设置
   if (inout.empty()) {
 #  ifdef WIN32
     inout = file_system::getenv("TMP");
@@ -379,6 +380,7 @@ ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inou
 
 #  if (defined(ATFRAMEWORK_UTILS_ENABLE_WINDOWS_MKTEMP) && ATFRAMEWORK_UTILS_ENABLE_WINDOWS_MKTEMP)
 #    if defined(UTIL_FS_C11_API)
+  // Windows实现 - C11 API
   if (0 == _mktemp_s(&inout[0], inout.size())) {
     inout.pop_back();
     return true;
@@ -387,6 +389,7 @@ ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inou
     return false;
   }
 #    else
+  // Windows实现 - 传统 API
   if (nullptr != _mktemp(&inout[0])) {
     inout.pop_back();
     return true;
@@ -396,6 +399,7 @@ ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inou
   }
 #    endif
 #  else
+  // 传统 C API
   int tmp_fd = mkstemp(&inout[0]);
   if (-1 == tmp_fd) {
     inout.clear();
@@ -422,6 +426,7 @@ ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inou
 #    pragma clang diagnostic ignored "-Wdeprecated-declarations"
 #  endif
 
+  // Posix实现 - C11 API
 #  if defined(UTIL_FS_C11_API)
 #    if defined(L_tmpnam_s)
   char path_buffer[L_tmpnam_s + 1] = {0};
@@ -437,6 +442,7 @@ ATFRAMEWORK_UTILS_API bool file_system::generate_tmp_file_name(std::string &inou
     return false;
   }
 #  else
+// Posix实现 - 传统 API
 #    if defined(L_tmpnam)
   char path_buffer[L_tmpnam + 1] = {0};
   path_buffer[L_tmpnam] = 0;
@@ -478,6 +484,7 @@ ATFRAMEWORK_UTILS_API int file_system::scan_dir(const char *dir_path, std::list<
 
 #ifdef UTIL_FS_WINDOWS_API
 
+  // Windows 选项转换
   if (!base_dir.empty()) {
     base_dir += DIRECTORY_SEPARATOR;
   }

src/log/log_formatter.cpp

@@ -65,6 +65,7 @@ ATFRAMEWORK_UTILS_API size_t log_formatter::format(char *buff, size_t bufz, cons
     return 0;
   }
 
+  // Level id to level name
   gsl::string_view level_name = caller.level_name;
   if (level_name.empty()) {
     level_name = detail::log_formatter_get_level_name(caller.level_id);
@@ -100,7 +101,9 @@ ATFRAMEWORK_UTILS_API size_t log_formatter::format(char *buff, size_t bufz, cons
     }
 
     need_parse = false;
-    // 以后再优化
+    // 简化版本的 strftime 格式支持
+    // @see https://en.cppreference.com/w/cpp/chrono/c/strftime
+    // 额外支持毫秒，rotate index, log level 名称等
     switch (fmt[i]) {
       // =================== datetime ===================
       case 'Y': {

src/network/http_request.cpp

@@ -125,6 +125,7 @@ ATFRAMEWORK_UTILS_API int http_request::start(method_t::type method, bool wait)
     return -1;
   }
 
+  // HTTP Method转换
   switch (method) {
     case method_t::EN_MT_GET:
       curl_easy_setopt(req, CURLOPT_HTTPGET, 1L);
@@ -150,8 +151,10 @@ ATFRAMEWORK_UTILS_API int http_request::start(method_t::type method, bool wait)
   }
 
   last_error_code_ = CURLE_OK;
+  // 构建提交表单缓存，维持生命周期
   build_http_form(method);
 
+  // 常见选项的跨版本兼容性适配
 #    if LIBCURL_VERSION_NUM >= 0x073800
   if (nullptr != http_form_.multipart) {
 #    else
@@ -206,11 +209,13 @@ ATFRAMEWORK_UTILS_API int http_request::start(method_t::type method, bool wait)
     set_opt_long(CURLOPT_CONNECTTIMEOUT_MS, connect_timeout_ms_);
   }
 
+  // 绑定到共享的EventLoop驱动层
   if (share_context_ && nullptr != share_context_->get_share_handle()) {
     curl_easy_setopt(req, CURLOPT_SHARE, share_context_->get_share_handle());
   }
 
   int perform_result;
+  // 同时支持同步模式和异步模式
   if (wait) {
     SET_FLAG(flags_, flag_t::EN_FT_RUNNING);
     perform_result = curl_easy_perform(req);