docs: doxygen annotations for curves + mesh + sketch

include/vde/core/triangle.h

@@ -4,24 +4,89 @@
 
 namespace vde::core {
 
+/**
+ * @brief 三维三角形
+ *
+ * 由三个顶点定义的平面三角形面片。
+ * 支持面积、法线、质心、重心坐标包含测试。
+ *
+ * @tparam T 标量类型（通常为 double）
+ *
+ * @ingroup core
+ */
 template <typename T>
 class Triangle {
 public:
+    /// 默认构造：三个顶点均在原点（退化三角形）
     Triangle() = default;
+
+    /**
+     * @brief 从三个顶点构造三角形
+     *
+     * @param v0 第一个顶点
+     * @param v1 第二个顶点
+     * @param v2 第三个顶点
+     */
     Triangle(const Point3D& v0, const Point3D& v1, const Point3D& v2)
         : v_{v0, v1, v2} {}
 
+    /**
+     * @brief 获取第 i 个顶点
+     *
+     * @param i 顶点索引（0, 1, 2）
+     * @return 顶点引用
+     */
     [[nodiscard]] const Point3D& v(int i) const { return v_[i]; }
+
+    /// 获取所有顶点数组
     [[nodiscard]] const std::array<Point3D, 3>& vertices() const { return v_; }
+
+    /**
+     * @brief 三角形单位法向量
+     *
+     * 使用 (v1 - v0) × (v2 - v0) 的归一化结果。
+     * 依右手定则方向。
+     *
+     * @return 单位法向量
+     *
+     * @note 若三角形退化（面积为零），返回零向量
+     */
     [[nodiscard]] Vector3D normal() const {
         return (v_[1] - v_[0]).cross(v_[2] - v_[0]).normalized();
     }
+
+    /**
+     * @brief 三角形面积
+     * @return 0.5 * ||(v1 - v0) × (v2 - v0)||
+     */
     [[nodiscard]] T area() const {
         return (v_[1] - v_[0]).cross(v_[2] - v_[0]).norm() * 0.5;
     }
+
+    /**
+     * @brief 三角形质心（几何中心）
+     * @return (v0 + v1 + v2) / 3
+     */
     [[nodiscard]] Point3D centroid() const {
         return (v_[0] + v_[1] + v_[2]) / 3.0;
     }
+
+    /**
+     * @brief 重心坐标包含测试
+     *
+     * 将点 p 正交投影到三角形平面上，计算重心坐标并判断是否在三角形内。
+     *
+     * @param p 测试点（三维空间中的任意点）
+     * @return true 若投影点在三角形内部或边界上
+     *
+     * @note 该测试等效于三维点在三角形上的包含测试（先投影再测试）
+     *
+     * @code{.cpp}
+     * Triangle3D tri({0,0,0}, {1,0,0}, {0,1,0});
+     * bool in1 = tri.contains(Point3D(0.2, 0.2, 0));  // true
+     * bool in2 = tri.contains(Point3D(0.2, 0.2, 5));  // true (投影后判断)
+     * @endcode
+     */
     [[nodiscard]] bool contains(const Point3D& p) const {
         Vector3D v0 = v_[2] - v_[0], v1 = v_[1] - v_[0], v2 = p - v_[0];
         T d00 = v0.dot(v0), d01 = v0.dot(v1), d11 = v1.dot(v1);
@@ -36,7 +101,9 @@ private:
     std::array<Point3D, 3> v_{};
 };
 
+/// 双精度三维三角形
 using Triangle3D = Triangle<double>;
+/// 单精度三维三角形
 using Triangle3f = Triangle<float>;
 
 }  // namespace vde::core