新建一个分支，用做源码中文注释

base/array.h

@@ -1,6 +1,11 @@
 #ifndef HV_ARRAY_H_
 #define HV_ARRAY_H_
 
+/*
+ * @功能：不定长数组的宏实现
+ *
+ */
+
 /*
  * array
  * at: random access by pos

base/hatomic.h

@@ -1,6 +1,11 @@
 #ifndef HV_ATOMIC_H_
 #define HV_ATOMIC_H_
 
+/*
+ * @功能：原子操作的跨平台封装
+ *
+ */
+
 #ifdef __cplusplus
 
 // c++11
@@ -93,6 +98,7 @@ static inline void atomic_flag_clear(atomic_flag* p) {
 }
 #endif
 
+// 垫底逻辑
 #ifndef ATOMIC_ADD
 #define ATOMIC_ADD(p, n)    (*(p) += (n))
 #endif

base/hbase.c

@@ -18,6 +18,7 @@ long hv_free_cnt() {
 }
 
 void* safe_malloc(size_t size) {
+    // 原子增加内存分配计数
     hatomic_inc(&s_alloc_cnt);
     void* ptr = malloc(size);
     if (!ptr) {
@@ -28,13 +29,16 @@ void* safe_malloc(size_t size) {
 }
 
 void* safe_realloc(void* oldptr, size_t newsize, size_t oldsize) {
+    // 原子增加内存分配计数
     hatomic_inc(&s_alloc_cnt);
+    // 原子增加内存释放计数
     hatomic_inc(&s_free_cnt);
     void* ptr = realloc(oldptr, newsize);
     if (!ptr) {
         fprintf(stderr, "realloc failed!\n");
         exit(-1);
     }
+    // 将新增的内存置0（系统库里的realloc未置空）
     if (newsize > oldsize) {
         memset((char*)ptr + oldsize, 0, newsize - oldsize);
     }
@@ -74,6 +78,7 @@ char* strupper(char* str) {
     char* p = str;
     while (*p != '\0') {
         if (*p >= 'a' && *p <= 'z') {
+            // 大小写只有bits[5]不同，利用这一特性，使用位操作符比加减操作更高效
             *p &= ~0x20;
         }
         ++p;
@@ -85,6 +90,7 @@ char* strlower(char* str) {
     char* p = str;
     while (*p != '\0') {
         if (*p >= 'A' && *p <= 'Z') {
+            // 大小写只有bits[5]不同，利用这一特性，使用位操作符比加减操作更高效
             *p |= 0x20;
         }
         ++p;
@@ -96,9 +102,10 @@ char* strreverse(char* str) {
     if (str == NULL) return NULL;
     char* b = str;
     char* e = str;
-    while(*e) {++e;}
-    --e;
+    while(*e) {++e;} // 此时e指向‘\0’结束符
+    --e; // 此时e指向最后一个字符
     char tmp;
+    // 头尾指针法
     while (e > b) {
         tmp = *e;
         *e = *b;
@@ -138,6 +145,7 @@ bool strstartswith(const char* str, const char* start) {
         ++str;
         ++start;
     }
+    // 如果start走到了'\0'结束符，说明str是以start开头
     return *start == '\0';
 }
 
@@ -145,9 +153,11 @@ bool strendswith(const char* str, const char* end) {
     assert(str != NULL && end != NULL);
     int len1 = 0;
     int len2 = 0;
-    while (*str) {++str; ++len1;}
-    while (*end) {++end; ++len2;}
+    while (*str) {++str; ++len1;} // 统计str的长度，str此时走到了'\0'结束符
+    while (*end) {++end; ++len2;} // 统计end的长度，end此时走到了'\0'结束符
+    // 如果str的长度比end的长度还小，当然不可能是以end字符串结尾，直接返回false
     if (len1 < len2) return false;
+    // 从最后一个字符开始比较是否相等
     while (len2-- > 0) {
         --str;
         --end;
@@ -160,6 +170,7 @@ bool strendswith(const char* str, const char* end) {
 
 bool strcontains(const char* str, const char* sub) {
     assert(str != NULL && sub != NULL);
+    // 直接使用了标准库函数strstr
     return strstr(str, sub) != NULL;
 }
 
@@ -168,8 +179,10 @@ char* strrchr_dir(const char* filepath) {
     while (*p) ++p;
     while (--p >= filepath) {
 #ifdef OS_WIN
+        // windows下通常以正斜杠‘\’表示路径分隔符
         if (*p == '/' || *p == '\\')
 #else
+        // unix下以反斜杠‘/’表示路径分隔符
         if (*p == '/')
 #endif
             return p;
@@ -178,16 +191,19 @@ char* strrchr_dir(const char* filepath) {
 }
 
 const char* hv_basename(const char* filepath) {
+    // 找到最后一个路径分割符，返回pos+1
     const char* pos = strrchr_dir(filepath);
     return pos ? pos+1 : filepath;
 }
 
 const char* hv_suffixname(const char* filename) {
+    // 找到最后一个点符号，返回pos+1
     const char* pos = strrchr_dot(filename);
     return pos ? pos+1 : "";
 }
 
 int hv_mkdir_p(const char* dir) {
+    // 如果路径可访问，说明路径已经存在，直接返回
     if (access(dir, 0) == 0) {
         return EEXIST;
     }
@@ -195,6 +211,7 @@ int hv_mkdir_p(const char* dir) {
     safe_strncpy(tmp, dir, sizeof(tmp));
     char* p = tmp;
     char delim = '/';
+    // 通过路径分隔符，一级一级的创建子目录
     while (*p) {
 #ifdef OS_WIN
         if (*p == '/' || *p == '\\') {
@@ -208,6 +225,7 @@ int hv_mkdir_p(const char* dir) {
         }
         ++p;
     }
+    // 创建最后一级目录
     if (hv_mkdir(tmp) != 0) {
         return EPERM;
     }
@@ -215,9 +233,11 @@ int hv_mkdir_p(const char* dir) {
 }
 
 int hv_rmdir_p(const char* dir) {
+    // 如果路径不可访问，说明路径不存在，直接返回
     if (access(dir, 0) != 0) {
         return ENOENT;
     }
+    // 删除最后一级目录
     if (rmdir(dir) != 0) {
         return EPERM;
     }
@@ -225,6 +245,7 @@ int hv_rmdir_p(const char* dir) {
     safe_strncpy(tmp, dir, sizeof(tmp));
     char* p = tmp;
     while (*p) ++p;
+    // 通过路径分隔符，一级一级的删除父目录
     while (--p >= tmp) {
 #ifdef OS_WIN
         if (*p == '/' || *p == '\\') {
@@ -244,6 +265,8 @@ bool getboolean(const char* str) {
     if (str == NULL) return false;
     int len = strlen(str);
     if (len == 0) return false;
+    // 通过长度判断后再和对应字符串做比较，
+    // 而不需要和每个代表true的字符串都对比一遍。
     switch (len) {
     case 1: return *str == '1' || *str == 'y' || *str == 'Y';
     case 2: return stricmp(str, "on") == 0;
@@ -254,6 +277,7 @@ bool getboolean(const char* str) {
     }
 }
 
+// 获取可执行文件路径在各个操作系统上的实现不同，这里提供统一的封装接口
 char* get_executable_path(char* buf, int size) {
 #ifdef OS_WIN
     GetModuleFileName(NULL, buf, size);

base/hbase.h

@@ -1,12 +1,18 @@
 #ifndef HV_BASE_H_
 #define HV_BASE_H_
 
+/*
+ * @功能：此头文件实现了一些常用的函数
+ *
+ */
+
 #include "hexport.h"
 #include "hplatform.h" // for bool
 #include "hdef.h" // for printd
 
 BEGIN_EXTERN_C
 
+// 安全的内存分配与释放函数
 //--------------------safe alloc/free---------------------------
 HV_EXPORT void* safe_malloc(size_t size);
 HV_EXPORT void* safe_realloc(void* oldptr, size_t newsize, size_t oldsize);
@@ -14,14 +20,17 @@ HV_EXPORT void* safe_calloc(size_t nmemb, size_t size);
 HV_EXPORT void* safe_zalloc(size_t size);
 HV_EXPORT void  safe_free(void* ptr);
 
+// 分配内存宏
 #define HV_ALLOC(ptr, size)\
     do {\
         *(void**)&(ptr) = safe_zalloc(size);\
         printd("alloc(%p, size=%llu)\tat [%s:%d:%s]\n", ptr, (unsigned long long)size, __FILE__, __LINE__, __FUNCTION__);\
     } while(0)
 
+// 通过sizeof计算内存占用大小，并分配内存，通常用于给结构体分配内存
 #define HV_ALLOC_SIZEOF(ptr)  HV_ALLOC(ptr, sizeof(*(ptr)))
 
+// 释放内存宏
 #define HV_FREE(ptr)\
     do {\
         if (ptr) {\
@@ -31,6 +40,7 @@ HV_EXPORT void  safe_free(void* ptr);
         }\
     } while(0)
 
+// 统计内存分配/释放的次数，以此检查是否有内存未释放
 HV_EXPORT long hv_alloc_cnt();
 HV_EXPORT long hv_free_cnt();
 static inline void hv_memcheck() {
@@ -38,15 +48,25 @@ static inline void hv_memcheck() {
 }
 #define HV_MEMCHECK    atexit(hv_memcheck);
 
+// 一些字符串操作函数
 //--------------------safe string-------------------------------
+// 字符串转大写
 HV_EXPORT char* strupper(char* str);
+// 字符串转小写
 HV_EXPORT char* strlower(char* str);
+// 字符串翻转
 HV_EXPORT char* strreverse(char* str);
 
+// 判断字符串是否以某个字符串开头
 HV_EXPORT bool strstartswith(const char* str, const char* start);
+// 判断字符串是否以某个字符串结尾
 HV_EXPORT bool strendswith(const char* str, const char* end);
+// 判断字符串中是否包含某个子串
 HV_EXPORT bool strcontains(const char* str, const char* sub);
 
+// 标准库里的strncpy、strncat通常需要传入sizeof(dest_buf)-1，
+// 如果不小心传成sizeof(dest_buf)，可能造成内存越界访问以及不是以'\0'结尾，
+// 所以这里重新实现了下，传入sizeof(dest_buf)也能安全工作
 // strncpy n = sizeof(dest_buf)-1
 // safe_strncpy n = sizeof(dest_buf)
 HV_EXPORT char* safe_strncpy(char* dest, const char* src, size_t n);
@@ -55,6 +75,7 @@ HV_EXPORT char* safe_strncpy(char* dest, const char* src, size_t n);
 // safe_strncpy n = sizeof(dest_buf)
 HV_EXPORT char* safe_strncat(char* dest, const char* src, size_t n);
 
+// 某些系统库里没有定义strlcpy和strlcat，这里兼容处理下
 #if !HAVE_STRLCPY
 #define strlcpy safe_strncpy
 #endif
@@ -63,23 +84,34 @@ HV_EXPORT char* safe_strncat(char* dest, const char* src, size_t n);
 #define strlcat safe_strncat
 #endif
 
+// 查找最后一个点符号，通常用于分离文件名和后缀
 #define strrchr_dot(str) strrchr(str, '.')
+// 查找最后一个路径符号，通常用于分离路径和文件名
 HV_EXPORT char* strrchr_dir(const char* filepath);
 
 // basename
+// 获取文件名，使用上面的strrchr_dir实现
 HV_EXPORT const char* hv_basename(const char* filepath);
+// 获取后缀名，使用上面的strrchr_dot实现
 HV_EXPORT const char* hv_suffixname(const char* filename);
 // mkdir -p
+// 递归创建文件夹
 HV_EXPORT int hv_mkdir_p(const char* dir);
 // rmdir -p
+// 递归删除文件夹
 HV_EXPORT int hv_rmdir_p(const char* dir);
 
 // 1 y on yes true enable
+// 根据字符串返回对应表示的布尔类型值
 HV_EXPORT bool getboolean(const char* str);
 
+// 获取可执行文件完整路径
 HV_EXPORT char* get_executable_path(char* buf, int size);
+// 获取可执行文件所在目录
 HV_EXPORT char* get_executable_dir(char* buf, int size);
+// 获取可执行文件名
 HV_EXPORT char* get_executable_file(char* buf, int size);
+// 获取运行目录
 HV_EXPORT char* get_run_dir(char* buf, int size);
 
 END_EXTERN_C

base/hbuf.h

@@ -1,6 +1,11 @@
 #ifndef HV_BUF_H_
 #define HV_BUF_H_
 
+/*
+ * @功能：此头文件提供了一些常用的buffer
+ *
+ */
+
 #include "hdef.h"   // for MAX
 #include "hbase.h"  // for HV_ALLOC, HV_FREE
 
@@ -21,6 +26,8 @@ typedef struct hbuf_s {
 #endif
 } hbuf_t;
 
+// offset_buf_t 多了一个offset偏移量成员变量，
+// 通常用于一次未操作完，记录下一次操作的起点
 typedef struct offset_buf_s {
     char*   base;
     size_t  len;
@@ -44,6 +51,7 @@ public:
     HBuf() : hbuf_t() {
         cleanup_ = false;
     }
+    // 浅拷贝构造函数
     HBuf(void* data, size_t len) : hbuf_t(data, len) {
         cleanup_ = false;
     }
@@ -79,6 +87,7 @@ public:
         cleanup_ = true;
     }
 
+    // 深拷贝
     void copy(void* data, size_t len) {
         resize(len);
         memcpy(base, data, len);
@@ -89,9 +98,10 @@ public:
     }
 
 private:
-    bool cleanup_;
+    bool cleanup_; // cleanup_变量用来记录buf是浅拷贝还是深拷贝，如果是深拷贝，析构时需释放掉分配内存
 };
 
+// 可变长buffer类型，支持push_front/push_back/pop_front/pop_back操作
 // VL: Variable-Length
 class HVLBuf : public HBuf {
 public:
@@ -100,66 +110,85 @@ public:
     HVLBuf(size_t cap) : HBuf(cap) {_offset = _size = 0;}
     virtual ~HVLBuf() {}
 
+    // 返回当前起点
     char* data() { return base + _offset; }
+    // 返回有效长度
     size_t size() { return _size; }
 
     void push_front(void* ptr, size_t len) {
+        // 如果插入长度超过了剩余空间，则重新分配足够空间
         if (len > this->len - _size) {
             size_t newsize = MAX(this->len, len)*2;
             base = (char*)safe_realloc(base, newsize, this->len);
             this->len = newsize;
         }
 
+        // 如果前面空间不足，则需要先整体后移
         if (_offset < len) {
             // move => end
             memmove(base+this->len-_size, data(), _size);
             _offset = this->len-_size;
         }
 
+        // 插入到当前起点的前面
         memcpy(data()-len, ptr, len);
+        // 记录新的起点位置
         _offset -= len;
+        // 有效长度增加
         _size += len;
     }
 
     void push_back(void* ptr, size_t len) {
+        // 如果插入长度超过了剩余空间，则重新分配足够空间
         if (len > this->len - _size) {
             size_t newsize = MAX(this->len, len)*2;
             base = (char*)safe_realloc(base, newsize, this->len);
             this->len = newsize;
         }
+        // 如果后面空间不足，则需要先整体前移
         else if (len > this->len - _offset - _size) {
             // move => start
             memmove(base, data(), _size);
             _offset = 0;
         }
+        // 插入到后面
         memcpy(data()+_size, ptr, len);
+        // 起点位置不变，有效长度增加
         _size += len;
     }
 
     void pop_front(void* ptr, size_t len) {
         if (len <= _size) {
+            // 将数据从开始位置拷贝出来
             if (ptr) {
                 memcpy(ptr, data(), len);
             }
+            // 起点位置后移
             _offset += len;
+            // 如果起点位置已经到了结尾，则重置为0
             if (_offset >= this->len) _offset = 0;
+            // 有效长度减少
             _size   -= len;
         }
     }
 
     void pop_back(void* ptr, size_t len) {
         if (len <= _size) {
+            // 将数据从尾部拷贝出来
             if (ptr) {
                 memcpy(ptr, data()+_size-len, len);
             }
+            // 起点位置不变，有效长度减少
             _size -= len;
         }
     }
 
     void clear() {
+        // 清除操作：将起点位置和有效长度重置为0
         _offset = _size = 0;
     }
 
+    // 一些别名函数
     void prepend(void* ptr, size_t len) {
         push_front(ptr, len);
     }
@@ -177,10 +206,11 @@ public:
     }
 
 private:
-    size_t _offset;
-    size_t _size;
+    size_t _offset; // _offet用来记录当前起点的偏移量
+    size_t _size; // _size用来记录有效长度
 };
 
+// 环形buffer：有序从环形buffer中分配与释放内存，避免频繁调用系统调用
 class HRingBuf : public HBuf {
 public:
     HRingBuf() : HBuf() {_head = _tail = _size = 0;}
@@ -189,13 +219,16 @@ public:
 
     char* alloc(size_t len) {
         char* ret = NULL;
+        // 如果头指针在尾指针前面或者已用长度等于0
         if (_head < _tail || _size == 0) {
             // [_tail, this->len) && [0, _head)
+            // 如果尾指针后面剩余空间足够，则从尾指针后开始分配空间
             if (this->len - _tail >= len) {
                 ret = base + _tail;
                 _tail += len;
                 if (_tail == this->len) _tail = 0;
             }
+            // 如果头指针前面剩余空间足够，则从0开始分配空间
             else if (_head >= len) {
                 ret = base;
                 _tail = len;
@@ -203,21 +236,26 @@ public:
         }
         else {
             // [_tail, _head)
+            // 如果尾指针到头指针间的空间足够，则从尾指针后开始分配空间
             if (_head - _tail >= len) {
                 ret = base + _tail;
                 _tail += len;
             }
         }
+        // 分配到了空间，已用长度增加
         _size += ret ? len : 0;
         return ret;
     }
 
     void free(size_t len) {
+        // 已用长度减少
         _size -= len;
+        // 如果释放的长度小于头指针后面的长度，头指针后移，
         if (len <= this->len - _head) {
             _head += len;
             if (_head == this->len) _head = 0;
         }
+        // 否则说明头指针已抵尾部，这块释放的内存是从0开始分配的，头指针置为len即可
         else {
             _head = len;
         }
@@ -228,9 +266,9 @@ public:
     size_t size() {return _size;}
 
 private:
-    size_t _head;
-    size_t _tail;
-    size_t _size;
+    size_t _head; // 头指针，用来记录读位置
+    size_t _tail; // 尾指针，用来记录写位置
+    size_t _size; // 用来记录已用长度
 };
 #endif
 

base/hdef.h

@@ -1,32 +1,45 @@
 #ifndef HV_DEF_H_
 #define HV_DEF_H_
 
+/*
+ * @功能：此头文件定义了一些常用宏
+ *
+ */
+
 #include "hplatform.h"
 
+// 取绝对值
 #ifndef ABS
 #define ABS(n)  ((n) > 0 ? (n) : -(n))
 #endif
 
+// 取负绝对值
 #ifndef NABS
 #define NABS(n) ((n) < 0 ? (n) : -(n))
 #endif
 
+// 数组大小
 #ifndef ARRAY_SIZE
 #define ARRAY_SIZE(a) (sizeof(a) / sizeof(*(a)))
 #endif
 
+// 设置bit位
 #ifndef BITSET
 #define BITSET(p, n) (*(p) |= (1u << (n)))
 #endif
 
+// 清除bit位
 #ifndef BITCLR
 #define BITCLR(p, n) (*(p) &= ~(1u << (n)))
 #endif
 
+// 获取bit位
 #ifndef BITGET
 #define BITGET(i, n) ((i) & (1u << (n)))
 #endif
 
+// 换行符
+// 因为历史原因，mac使用\r，linux使用\n，windows使用\r\n
 #ifndef CR
 #define CR      '\r'
 #endif
@@ -39,13 +52,16 @@
 #define CRLF    "\r\n"
 #endif
 
+// float == 0 的写法
 #define FLOAT_PRECISION     1e-6
 #define FLOAT_EQUAL_ZERO(f) (ABS(f) < FLOAT_PRECISION)
 
+// 定义一个表示永远的值
 #ifndef INFINITE
 #define INFINITE    (uint32_t)-1
 #endif
 
+// ASCII码
 /*
 ASCII:
 [0, 0x20)    control-charaters
@@ -62,46 +78,57 @@ ASCII:
 [0x61, 0x7A] => a~z
 */
 
+// 判断是否为字母
 #ifndef IS_ALPHA
 #define IS_ALPHA(c) (((c) >= 'a' && (c) <= 'z') || ((c) >= 'A' && (c) <= 'Z'))
 #endif
 
+// 判断是否为数字
 #ifndef IS_NUM
 #define IS_NUM(c)   ((c) >= '0' && (c) <= '9')
 #endif
 
+// 判断是否为字母或数字
 #ifndef IS_ALPHANUM
 #define IS_ALPHANUM(c) (IS_ALPHA(c) || IS_NUM(c))
 #endif
 
+// 判断是否为控制符
 #ifndef IS_CNTRL
 #define IS_CNTRL(c) ((c) >= 0 && (c) < 0x20)
 #endif
 
+// 判断是否为可打印符
 #ifndef IS_GRAPH
 #define IS_GRAPH(c) ((c) >= 0x20 && (c) < 0x7F)
 #endif
 
+// 判断是否为16进制
 #ifndef IS_HEX
 #define IS_HEX(c) (IS_NUM(c) || ((c) >= 'a' && (c) <= 'f') || ((c) >= 'A' && (c) <= 'F'))
 #endif
 
+// 判断是否为小写字母
 #ifndef IS_LOWER
 #define IS_LOWER(c) (((c) >= 'a' && (c) <= 'z'))
 #endif
 
+// 判断是否为大写字母
 #ifndef IS_UPPER
 #define IS_UPPER(c) (((c) >= 'A' && (c) <= 'Z'))
 #endif
 
+// 转小写
 #ifndef LOWER
 #define LOWER(c)    ((c) | 0x20)
 #endif
 
+// 转大写
 #ifndef UPPER
 #define UPPER(c)    ((c) & ~0x20)
 #endif
 
+// 定义一些整型显示转换宏
 // LD, LU, LLD, LLU for explicit conversion of integer
 #ifndef LD
 #define LD(v)   ((long)(v))
@@ -228,33 +255,45 @@ ASCII:
 #define SAFE_RELEASE(p) do {if (p) {(p)->release(); (p) = NULL;}} while(0)
 #endif
 
+/*
+ * @NOTE: 宏定义中的三个特殊符号：#，##，#@
+ * #define TOSTR(x)     #x      // 给x加上双引号
+ * #define TOCHAR(x)    #@x     // 给x加上单引号
+ * #define STRCAT(x,y)  x##y    // 连接x和y成一个字符串
+ *
+ */
 #define STRINGIFY(x)    STRINGIFY_HELPER(x)
 #define STRINGIFY_HELPER(x)     #x
 
 #define STRINGCAT(x, y)  STRINGCAT_HELPER(x, y)
 #define STRINGCAT_HELPER(x, y)  x##y
 
+// 获取结构体成员偏移量
 #ifndef offsetof
 #define offsetof(type, member) \
 ((size_t)(&((type*)0)->member))
 #endif
 
+// 获取结构体成员尾部的偏移量
 #ifndef offsetofend
 #define offsetofend(type, member) \
 (offsetof(type, member) + sizeof(((type*)0)->member))
 #endif
 
+// 根据结构体成员指针获取结构体指针
 #ifndef container_of
 #define container_of(ptr, type, member) \
 ((type*)((char*)(ptr) - offsetof(type, member)))
 #endif
 
+// DEBUG打印宏
 #ifdef PRINT_DEBUG
 #define printd(...) printf(__VA_ARGS__)
 #else
 #define printd(...)
 #endif
 
+// ERROR打印宏
 #ifdef PRINT_ERROR
 #define printe(...) fprintf(stderr, __VA_ARGS__)
 #else

base/hplatform.h

@@ -1,9 +1,15 @@
 #ifndef HV_PLATFORM_H_
 #define HV_PLATFORM_H_
 
+/*
+ * @功能：此头文件主要定义了平台相关宏
+ *
+ */
+
 #include "hconfig.h"
 
 // OS
+// 操作系统宏
 #if defined(WIN64) || defined(_WIN64)
     #define OS_WIN64
     #define OS_WIN32
@@ -45,6 +51,7 @@
 #endif
 
 // ARCH
+// CPU体系结构宏
 #if defined(__i386) || defined(__i386__) || defined(_M_IX86)
     #define ARCH_X86
     #define ARCH_X86_32
@@ -61,6 +68,7 @@
 #endif
 
 // COMPILER
+// 编译器宏
 #if defined (_MSC_VER)
 #define COMPILER_MSVC
 
@@ -106,6 +114,7 @@
 #undef  HAVE_PTHREAD_H
 #define HAVE_PTHREAD_H          0
 
+// 禁掉一些MSVC编译时警告
 #pragma warning (disable: 4018) // signed/unsigned comparison
 #pragma warning (disable: 4100) // unused param
 #pragma warning (disable: 4244) // conversion loss of data
@@ -132,6 +141,7 @@
 #endif
 
 // headers
+// #include一些常用头文件
 #ifdef OS_WIN
     #ifndef WIN32_LEAN_AND_MEAN
     #define WIN32_LEAN_AND_MEAN
@@ -195,6 +205,7 @@
 #endif
 
 // ENDIAN
+// 大小端宏
 #ifndef BIG_ENDIAN
 #define BIG_ENDIAN      4321
 #endif
@@ -206,6 +217,7 @@
 #endif
 
 // BYTE_ORDER
+// 字节序宏
 #ifndef BYTE_ORDER
 #if defined(ARCH_X86) || defined(ARCH_X86_64) || defined(__ARMEL__)
 #define BYTE_ORDER      LITTLE_ENDIAN
@@ -215,6 +227,7 @@
 #endif
 
 // ANSI C
+// #include ANSI C 标准头文件
 #include <assert.h>
 #include <stddef.h>
 #include <stdarg.h>
@@ -229,6 +242,8 @@
 #include <math.h>
 #include <signal.h>
 
+// bool类型兼容处理
+// c99前C语言是没有bool类型的
 #ifndef __cplusplus
 #if HAVE_STDBOOL_H
 #include <stdbool.h>
@@ -247,6 +262,7 @@
 #endif
 #endif
 
+// int类型兼容处理
 #if HAVE_STDINT_H
 #include <stdint.h>
 #elif defined(_MSC_VER) && _MSC_VER < 1700
@@ -266,6 +282,7 @@ typedef double              float64_t;
 typedef int (*method_t)(void* userdata);
 typedef void (*procedure_t)(void* userdata);
 
+// 根据生成的hconfig.h，#include一些非ANSI C 头文件
 #if HAVE_SYS_TYPES_H
 #include <sys/types.h>
 #endif

hexport.h

@@ -1,7 +1,15 @@
 #ifndef HV_EXPORT_H_
 #define HV_EXPORT_H_
 
+/*
+ * @功能: 此头文件主要是定义动态库导出宏HV_EXPORT
+ *
+ * @备注: 如果是以静态库方式使用，需将HV_STATICLIB加入到预编译宏
+ *
+ */
+
 // HV_EXPORT
+// 接口导出宏
 #if defined(HV_STATICLIB) || defined(HV_SOURCE)
     #define HV_EXPORT
 #elif defined(_MSC_VER)
@@ -17,6 +25,7 @@
 #endif
 
 // HV_DEPRECATED
+// 接口过时声明宏
 #if defined(HV_NO_DEPRECATED)
 #define HV_DEPRECATED
 #elif defined(__GNUC__) || defined(__clang__)
@@ -28,6 +37,7 @@
 #endif
 
 // HV_UNUSED
+// 参数未使用宏
 #if defined(__GNUC__)
     #define HV_UNUSED   __attribute__((visibility("unused")))
 #else
@@ -35,6 +45,13 @@
 #endif
 
 // @param[IN | OUT | INOUT]
+/*
+ * 参数描述宏：
+ * IN   => 输入参数
+ * OUT  => 输出参数
+ * INOUT=> 既作输入参数，又作输出参数
+ *
+ */
 #ifndef IN
 #define IN
 #endif
@@ -48,6 +65,13 @@
 #endif
 
 // @field[OPTIONAL | REQUIRED | REPEATED]
+/*
+ * 字段描述宏：
+ * OPTIONAL => 可选字段
+ * REQUIRED => 必需字段
+ * REPEATED => 可重复字段
+ *
+ */
 #ifndef OPTIONAL
 #define OPTIONAL
 #endif
@@ -62,6 +86,13 @@
 
 #ifdef __cplusplus
 
+/*
+ * @NOTE：extern "C"的作用
+ * 由于C++支持函数重载，而C语言不支持，因此函数被C++编译后在符号库中的名字是与C语言不同的；
+ * C++编译后的函数需要加上参数的类型才能唯一标定重载后的函数，
+ * 加上extern "C"，是为了向编译器指明这段代码按照C语言的方式进行编译。
+ *
+ */
 #ifndef EXTERN_C
 #define EXTERN_C            extern "C"
 #endif
@@ -74,6 +105,7 @@
 #define END_EXTERN_C        } // extern "C"
 #endif
 
+// 命名空间声明宏
 #ifndef BEGIN_NAMESPACE
 #define BEGIN_NAMESPACE(ns) namespace ns {
 #endif
@@ -86,14 +118,17 @@
 #define USING_NAMESPACE(ns) using namespace ns;
 #endif
 
+// 缺省值
 #ifndef DEFAULT
 #define DEFAULT(x)  = x
 #endif
 
+// 枚举类型声明
 #ifndef ENUM
 #define ENUM(e)     enum e
 #endif
 
+// 结构体类型声明
 #ifndef STRUCT
 #define STRUCT(s)   struct s
 #endif

hv.h

@@ -1,16 +1,23 @@
 #ifndef HV_H_
 #define HV_H_
 
+/*
+ * @功能: base模块下的头文件比较零散，所以提个了一个汇总的头文件，方便大家#include
+ *
+ */
+
 /**
  * @copyright 2018 HeWei, all rights reserved.
  */
 
 // platform
+// 平台相关头文件
 #include "hconfig.h"
 #include "hexport.h"
 #include "hplatform.h"
 
 // c
+// c语言头文件
 #include "hdef.h"   // <stddef.h>
 #include "hatomic.h"// <stdatomic.h>
 #include "herr.h"   // <errno.h>
@@ -30,6 +37,7 @@
 #include "hbuf.h"
 
 // cpp
+// c++语言头文件
 #ifdef __cplusplus
 #include "hmap.h"       // <map>
 #include "hstring.h"    // <string>