Add Comments

ReportEngine/core/template_parser.py

@@ -63,6 +63,12 @@ def parse_template_sections(template_md: str) -> List[TemplateSection]:
     返回的每个TemplateSection都携带slug/order/章节号，
     方便后续分章调用与锚点生成。解析时会同时兼容
     “# 标题”“无符号编号”“列表提纲”等不同写法。
+
+    参数:
+        template_md: 模板Markdown全文。
+
+    返回:
+        list[TemplateSection]: 结构化的章节序列。
     """
 
     sections: List[TemplateSection] = []
@@ -113,6 +119,13 @@ def _classify_line(stripped: str, indent: int) -> Optional[dict]:
 
     借助正则判断当前行是章节标题、提纲还是普通列表项，
     并衍生 depth/slug/number 等派生信息。
+
+    参数:
+        stripped: 去除前后空格后的原始行。
+        indent: 行首空格数量，用于区分层级。
+
+    返回:
+        dict | None: 识别后的元数据；无法识别时返回None。
     """
 
     heading_match = heading_pattern.match(stripped)
@@ -181,6 +194,12 @@ def _split_number(payload: str) -> dict:
 
     例如 `1.2 市场趋势` 会被拆成 number=1.2、label=市场趋势，
     并提供 display 用于回填标题。
+
+    参数:
+        payload: 原始标题字符串。
+
+    返回:
+        dict: 包含 number/title/display。
     """
     match = number_pattern.match(payload)
     number = match.group("num") if match else ""
@@ -196,7 +215,16 @@ def _split_number(payload: str) -> dict:
 
 
 def _build_slug(number: str, title: str) -> str:
-    """根据编号/标题生成锚点，优先复用编号，缺失时对标题slug化。"""
+    """
+    根据编号/标题生成锚点，优先复用编号，缺失时对标题slug化。
+
+    参数:
+        number: 章节编号。
+        title: 标题文本。
+
+    返回:
+        str: 形如 `section-1-0` 的slug。
+    """
     if number:
         token = number.replace(".", "-")
     else:
@@ -223,6 +251,13 @@ def _ensure_unique_slug(slug: str, used: set) -> str:
     若slug重复则自动追加序号，直到在used集合中唯一。
 
     通过 `-2/-3...` 的方式保证相同标题不会产生重复锚点。
+
+    参数:
+        slug: 初始slug。
+        used: 已使用集合。
+
+    返回:
+        str: 去重后的slug。
     """
     if slug not in used:
         used.add(slug)