init

contracts/libraries/Math.sol

@@ -1,17 +1,32 @@
 pragma solidity =0.5.16;
 
-// a library for performing various math operations
-
+/**
+ * @title Math 数学计算库
+ * @notice 提供各种数学运算函数
+ * @dev 包含最小值计算和平方根计算等工具函数
+ */
 library Math {
+    /**
+     * @notice 返回两个数中的较小值
+     * @param x 第一个数
+     * @param y 第二个数
+     * @return z 较小的数
+     */
     function min(uint x, uint y) internal pure returns (uint z) {
         z = x < y ? x : y;
     }
 
-    // babylonian method (https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method)
+    /**
+     * @notice 计算平方根（巴比伦算法）
+     * @dev 使用巴比伦方法计算平方根，参考: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method
+     * @param y 需要计算平方根的数
+     * @return z 平方根结果
+     */
     function sqrt(uint y) internal pure returns (uint z) {
         if (y > 3) {
             z = y;
             uint x = y / 2 + 1;
+            // 迭代逼近，直到找到最优解
             while (x < z) {
                 z = x;
                 x = (y / x + x) / 2;
@@ -19,5 +34,6 @@ library Math {
         } else if (y != 0) {
             z = 1;
         }
+        // 如果y为0，则z保持为0（默认值）
     }
 }

contracts/libraries/SafeMath.sol

@@ -1,16 +1,41 @@
 pragma solidity =0.5.16;
 
-// a library for performing overflow-safe math, courtesy of DappHub (https://github.com/dapphub/ds-math)
-
+/**
+ * @title SafeMath 安全数学运算库
+ * @notice 提供防止溢出的数学运算函数
+ * @dev 来自DappHub的ds-math库 (https://github.com/dapphub/ds-math)
+ * @dev 在Solidity 0.8.0之前，需要手动检查算术溢出
+ */
 library SafeMath {
+    /**
+     * @notice 安全加法，防止溢出
+     * @param x 第一个加数
+     * @param y 第二个加数
+     * @return z 两数之和
+     * @dev 如果结果溢出则回滚交易
+     */
     function add(uint x, uint y) internal pure returns (uint z) {
         require((z = x + y) >= x, 'ds-math-add-overflow');
     }
 
+    /**
+     * @notice 安全减法，防止下溢
+     * @param x 被减数
+     * @param y 减数
+     * @return z 两数之差
+     * @dev 如果结果下溢则回滚交易
+     */
     function sub(uint x, uint y) internal pure returns (uint z) {
         require((z = x - y) <= x, 'ds-math-sub-underflow');
     }
 
+    /**
+     * @notice 安全乘法，防止溢出
+     * @param x 第一个乘数
+     * @param y 第二个乘数  
+     * @return z 两数之积
+     * @dev 如果结果溢出则回滚交易，使用除法检查溢出
+     */
     function mul(uint x, uint y) internal pure returns (uint z) {
         require(y == 0 || (z = x * y) / y == x, 'ds-math-mul-overflow');
     }

contracts/libraries/UQ112x112.sol

@@ -1,19 +1,32 @@
 pragma solidity =0.5.16;
 
-// a library for handling binary fixed point numbers (https://en.wikipedia.org/wiki/Q_(number_format))
-
-// range: [0, 2**112 - 1]
-// resolution: 1 / 2**112
-
+/**
+ * @title UQ112x112 定点数运算库
+ * @notice 处理二进制定点数的库 (Q数字格式)
+ * @dev 参考: https://en.wikipedia.org/wiki/Q_(number_format)
+ * @dev 范围: [0, 2**112 - 1]，精度: 1 / 2**112
+ */
 library UQ112x112 {
+    // Q112常量，表示2^112，用于编码和解码
     uint224 constant Q112 = 2**112;
 
-    // encode a uint112 as a UQ112x112
+    /**
+     * @notice 将uint112编码为UQ112x112格式
+     * @param y 要编码的uint112数值
+     * @return z 编码后的UQ112x112数值
+     * @dev 乘以Q112进行编码，永不溢出
+     */
     function encode(uint112 y) internal pure returns (uint224 z) {
-        z = uint224(y) * Q112; // never overflows
+        z = uint224(y) * Q112; // 永不溢出
     }
 
-    // divide a UQ112x112 by a uint112, returning a UQ112x112
+    /**
+     * @notice UQ112x112除以uint112，返回UQ112x112
+     * @param x UQ112x112格式的被除数
+     * @param y uint112格式的除数
+     * @return z UQ112x112格式的商
+     * @dev 用于价格计算，保持定点数精度
+     */
     function uqdiv(uint224 x, uint112 y) internal pure returns (uint224 z) {
         z = x / uint224(y);
     }