docs: doxygen annotations for curves + mesh + sketch

include/vde/foundation/io_gltf.h

@@ -7,24 +7,76 @@
 
 namespace vde::foundation {
 
-/// GLTF export options
+/**
+ * @brief glTF 2.0 导出选项
+ *
+ * 控制网格以 glTF/GLB 格式导出的参数。
+ *
+ * @ingroup foundation
+ */
 struct GltfOptions {
-    bool binary = true;              // GLB (single file) vs glTF (JSON + .bin)
-    bool include_normals = true;     // Compute and export vertex normals
-    bool include_colors = false;     // Per-vertex colors
-    std::vector<float> vertex_colors; // RGB per vertex (if include_colors)
+    /// 是否以二进制 GLB 格式（单文件）输出；false 则输出 JSON + .bin 分离格式
+    bool binary = true;
+
+    /// 是否计算和导出顶点法线
+    bool include_normals = true;
+
+    /// 是否导出逐顶点颜色
+    bool include_colors = false;
+
+    /// 逐顶点 RGB 颜色数据（仅当 include_colors = true 时使用）
+    std::vector<float> vertex_colors;
 };
 
-/// Export mesh to glTF 2.0 / GLB
-/// Returns true on success
+/**
+ * @brief 导出网格为 glTF 2.0 / GLB 格式
+ *
+ * 将 HalfedgeMesh 写入 glTF 2.0 规范文件。默认输出单文件 GLB 二进制格式，
+ * 可通过 GltfOptions 控制输出格式和包含的属性。
+ *
+ * @param filepath 输出文件路径（.glb 或 .gltf）
+ * @param mesh 要导出的半边网格
+ * @param options 导出选项（格式、法线、颜色等）
+ * @return true 导出成功
+ * @return false 导出失败（文件无法创建等）
+ *
+ * @note 生成的 glTF 符合 2.0 规范，兼容 Blender、three.js、Unreal Engine 等工具
+ *
+ * @code{.cpp}
+ * mesh::HalfedgeMesh mesh = /* ... */;
+ * GltfOptions opts;
+ * opts.binary = true;
+ * opts.include_normals = true;
+ * bool ok = write_gltf("output.glb", mesh, opts);
+ * @endcode
+ *
+ * @see write_brep_gltf, GltfOptions
+ * @ingroup foundation
+ */
 bool write_gltf(const std::string& filepath, const mesh::HalfedgeMesh& mesh,
                 const GltfOptions& options = GltfOptions{});
 
-/// Export B-Rep model to GLB by tessellating faces
-/// @param filepath Output file (.glb recommended)
-/// @param model B-Rep model to export
-/// @param tessellation_res Resolution for curved surfaces (segments per edge)
-/// @return true on success
+/**
+ * @brief 导出 B-Rep 模型为 GLB 格式（通过面片化）
+ *
+ * 将 B-Rep 模型的参数曲面离散化为三角网格后导出为 GLB。
+ * 曲面通过 tessellation_res 控制离散精度。
+ *
+ * @param filepath 输出文件路径（建议 .glb）
+ * @param model 要导出的 B-Rep 模型
+ * @param tessellation_res 每条边的离散段数（默认 32），越大越精确
+ * @return true 导出成功
+ * @return false 导出失败
+ *
+ * @code{.cpp}
+ * brep::BrepModel model = /* ... */;
+ * // 高精度曲面导出
+ * bool ok = write_brep_gltf("model.glb", model, 64);
+ * @endcode
+ *
+ * @see write_gltf
+ * @ingroup foundation
+ */
 bool write_brep_gltf(const std::string& filepath, const brep::BrepModel& model,
                      int tessellation_res = 32);