#!/usr/bin/env python3 from __future__ import annotations import re from dataclasses import dataclass from pathlib import Path from generate_core_resources_canonical_pages import ( DOC_ROOT, INCLUDE_ROOT, REPO_ROOT, build_namespace_map, find_declarations, group_methods, select_primary, ) TEMPLATE_METHOD_TOKENS = ( "当前页面用于固定", "获取相关状态或对象。", "设置相关状态或配置。", "加载资源或数据。", "公开方法，详见头文件声明。", "参数语义详见头文件声明。", "返回值语义详见头文件声明。", ) TEMPLATE_TABLE_TOKENS = ( "获取相关状态或对象。", "设置相关状态或配置。", "加载资源或数据。", "公开方法，详见头文件声明。", ) GENERIC_FALLBACK_RE = re.compile( r"执行该公开方法对应的当前实现。|" r"返回 `[^`]+` 相关结果。|" r"更新 `[^`]+` 相关状态。|" r"判断 `[^`]+` 条件是否成立。|" r"判断是否具备 `[^`]+`。|" r"判断当前是否可以执行 `[^`]+`。" ) METHOD_SECTION_RE = re.compile(r"(?ms)^## 公共方法\n.*?(?=\n## |\Z)") BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL) LINE_COMMENT_RE = re.compile(r"//.*") RETURN_MEMBER_RE = re.compile(r"^return\s+(m_[A-Za-z_]\w*)\s*;?$") RETURN_MEMBER_METHOD_RE = re.compile( r"^return\s+(m_[A-Za-z_]\w*)\.(Data|data|Size|size|CStr|c_str|Get)\s*\((.*?)\)\s*;?$" ) RETURN_SIMPLE_CALL_RE = re.compile(r"^return\s+([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*\((.*)\)\s*;?$") RETURN_CONST_RE = re.compile(r"^return\s+([^;]+?)\s*;?$") ASSIGN_MEMBER_RE = re.compile(r"^(m_[A-Za-z_]\w*)\s*=\s*([^;]+?)\s*;?$") MEMBER_WRITE_RE = re.compile(r"\b(m_[A-Za-z_]\w*)\b\s*(?:=|\+=|-=|\*=|/=|%=|>>=|<<=|\+\+|--)") MEMBER_CALL_RE = re.compile(r"\b(m_[A-Za-z_]\w*)\.(\w+)\s*\(") DIRECT_CALL_RE = re.compile(r"\b([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*\(") ARROW_CALL_RE = re.compile(r"->\s*([A-Za-z_]\w*)\s*\(") DOT_CALL_RE = re.compile(r"\.\s*([A-Za-z_]\w*)\s*\(") FIELD_NAME_RE = re.compile(r"\bm_[A-Za-z_]\w*\b") KEYWORDS = { "if", "for", "while", "switch", "return", "sizeof", "static_cast", "reinterpret_cast", "const_cast", "dynamic_cast", "catch", "new", "delete", } MUTATING_MEMBER_CALLS = { "Append", "Assign", "Clear", "ClearDirty", "Emplace", "Erase", "Insert", "PopBack", "PushBack", "Release", "Remove", "Reset", "Resize", "Set", "SetInvalid", "Shrink", } @dataclass class ImplementationFact: summary: str | None details: list[str] @dataclass class ImplementationBlock: kind: str body: str def has_any_token(content: str, tokens: tuple[str, ...]) -> bool: return any(token in content for token in tokens) def has_generic_fallback(content: str) -> bool: return GENERIC_FALLBACK_RE.search(content) is not None def strip_comments(text: str) -> str: return LINE_COMMENT_RE.sub("", BLOCK_COMMENT_RE.sub("", text)) def normalize_whitespace(text: str) -> str: return " ".join(text.strip().split()) def split_statements(body: str) -> list[str]: parts: list[str] = [] current: list[str] = [] depth_paren = 0 depth_brace = 0 depth_angle = 0 for char in body: if char == "(": depth_paren += 1 elif char == ")": depth_paren = max(0, depth_paren - 1) elif char == "{": depth_brace += 1 elif char == "}": depth_brace = max(0, depth_brace - 1) elif char == "<": depth_angle += 1 elif char == ">": depth_angle = max(0, depth_angle - 1) if char == ";" and depth_paren == 0 and depth_brace == 0 and depth_angle == 0: statement = "".join(current).strip() if statement: parts.append(statement) current = [] continue current.append(char) tail = "".join(current).strip() if tail: parts.append(tail) return parts def camel_tail(name: str, prefix_len: int) -> str: tail = name[prefix_len:] return tail or name def format_identifier_list(items: list[str]) -> str: unique: list[str] = [] seen: set[str] = set() for item in items: if item in seen: continue unique.append(item) seen.add(item) return "、".join(f"`{item}`" for item in unique) def extract_balanced(text: str, start: int, open_char: str, close_char: str) -> tuple[str, int] | None: depth = 0 for index in range(start, len(text)): char = text[index] if char == open_char: depth += 1 elif char == close_char: depth -= 1 if depth == 0: return text[start:index + 1], index + 1 return None def scan_definition_suffix(text: str, start: int) -> tuple[str, int]: index = start while True: while index < len(text) and text[index].isspace(): index += 1 if text.startswith("const", index): index += len("const") continue if text.startswith("override", index): index += len("override") continue if text.startswith("final", index): index += len("final") continue if text.startswith("constexpr", index): index += len("constexpr") continue if text.startswith("noexcept", index): index += len("noexcept") while index < len(text) and text[index].isspace(): index += 1 if index < len(text) and text[index] == "(": extracted = extract_balanced(text, index, "(", ")") if extracted: _, index = extracted continue if index < len(text) and text[index] in {"&", "*"}: index += 1 continue break if text.startswith("= default", index): return "default", index + len("= default") if text.startswith("= delete", index): return "delete", index + len("= delete") if index < len(text) and text[index] == "{": return "body", index return "", index def extract_qualified_blocks(text: str, class_name: str, method_name: str) -> list[ImplementationBlock]: pattern = re.compile(rf"{re.escape(class_name)}\s*::\s*{re.escape(method_name)}\s*\(") blocks: list[ImplementationBlock] = [] for match in pattern.finditer(text): params_start = text.find("(", match.start()) extracted = extract_balanced(text, params_start, "(", ")") if not extracted: continue _, cursor = extracted kind, suffix_pos = scan_definition_suffix(text, cursor) if kind == "body": body_block = extract_balanced(text, suffix_pos, "{", "}") if body_block: body, _ = body_block blocks.append(ImplementationBlock(kind="body", body=body[1:-1])) elif kind in {"default", "delete"}: blocks.append(ImplementationBlock(kind=kind, body="")) return blocks def extract_inline_blocks(text: str, method_name: str) -> list[ImplementationBlock]: pattern = re.compile(rf"{re.escape(method_name)}\s*\(") blocks: list[ImplementationBlock] = [] for match in pattern.finditer(text): previous = text[match.start() - 1] if match.start() > 0 else "" if previous.isalnum() or previous in {":", ".", ">"}: continue params_start = text.find("(", match.start()) extracted = extract_balanced(text, params_start, "(", ")") if not extracted: continue _, cursor = extracted kind, suffix_pos = scan_definition_suffix(text, cursor) if kind == "body": body_block = extract_balanced(text, suffix_pos, "{", "}") if body_block: body, _ = body_block blocks.append(ImplementationBlock(kind="body", body=body[1:-1])) elif kind in {"default", "delete"}: blocks.append(ImplementationBlock(kind=kind, body="")) return blocks def summarize_return_value(expr: str) -> str: cleaned = normalize_whitespace(expr) if cleaned in {"true", "false", "nullptr"}: return f"固定返回 `{cleaned}`。" if FIELD_NAME_RE.fullmatch(cleaned): return f"返回 `{cleaned}` 当前值。" if cleaned.endswith("()"): return f"返回 `{cleaned}` 的结果。" return f"返回 `{cleaned}`。" def analyze_simple_statement(statement: str) -> ImplementationFact | None: normalized = normalize_whitespace(statement) if not normalized: return None match = RETURN_MEMBER_RE.match(normalized) if match: field = match.group(1) return ImplementationFact( summary=f"返回 `{field}` 当前值。", details=[f"内联返回 `{field}`。"], ) match = RETURN_MEMBER_METHOD_RE.match(normalized) if match: field, method, args = match.groups() if method.lower() == "data": summary = f"返回 `{field}` 暴露的首地址。" elif method.lower() == "size": summary = f"返回 `{field}` 当前大小。" elif method in {"CStr", "c_str"}: summary = f"返回 `{field}` 的 C 风格字符串视图。" else: summary = f"返回 `{field}.{method}()` 的结果。" detail = f"当前实现直接调用 `{field}.{method}({args})`。".replace("()", "()") return ImplementationFact(summary=summary, details=[detail]) match = ASSIGN_MEMBER_RE.match(normalized) if match: field, value = match.groups() return ImplementationFact( summary=f"写入 `{field}`。", details=[f"当前实现把 `{value}` 写入 `{field}`。"], ) match = RETURN_SIMPLE_CALL_RE.match(normalized) if match: call_name = match.group(1) return ImplementationFact( summary=f"返回 `{call_name}(...)` 的结果。", details=[f"当前实现直接转发到 `{call_name}(...)`。"], ) match = RETURN_CONST_RE.match(normalized) if match: return ImplementationFact( summary=summarize_return_value(match.group(1)), details=[summarize_return_value(match.group(1))], ) return None def collect_calls(body: str) -> list[str]: calls: list[str] = [] for regex in (DIRECT_CALL_RE, ARROW_CALL_RE, DOT_CALL_RE): for match in regex.finditer(body): name = match.group(1) short_name = name.split("::")[-1] if short_name in KEYWORDS: continue calls.append(short_name) return calls def collect_member_writes(body: str) -> list[str]: writes = MEMBER_WRITE_RE.findall(body) for field, method in MEMBER_CALL_RE.findall(body): if method in MUTATING_MEMBER_CALLS or method.startswith("Set"): writes.append(field) deduped: list[str] = [] seen: set[str] = set() for field in writes: if field in seen: continue deduped.append(field) seen.add(field) return deduped def analyze_complex_body(body: str) -> ImplementationFact: stripped = strip_comments(body) normalized = normalize_whitespace(stripped) statements = [normalize_whitespace(item) for item in split_statements(stripped)] if not normalized: return ImplementationFact( summary="当前实现为空。", details=["当前函数体为空。"], ) if len(statements) == 1: simple = analyze_simple_statement(statements[0]) if simple: return simple details: list[str] = [] summary: str | None = None writes = collect_member_writes(stripped) if writes: details.append(f"会更新 {format_identifier_list(writes[:4])}。") if len(writes) == 1 and summary is None: summary = f"更新 `{writes[0]}`。" calls = collect_calls(stripped) filtered_calls = [call for call in calls if call not in {"Get", "Set", "Data", "Size"}] if filtered_calls: details.append(f"当前实现会调用 {format_identifier_list(filtered_calls[:5])}。") if summary is None and len(filtered_calls) == 1: summary = f"执行 `{filtered_calls[0]}(...)` 相关流程。" elif summary is None: summary = f"执行 {format_identifier_list(filtered_calls[:3])} 协同流程。" return_values = re.findall(r"\breturn\s+([^;]+);", stripped) if len(return_values) > 1 or ("if (" in stripped and return_values): details.append("包含条件分支，并可能提前返回。") elif return_values and summary is None: summary = summarize_return_value(return_values[0]) if "nullptr" in stripped: details.append("包含 `nullptr` 相关分支。") if "not implemented" in stripped or "未实现" in stripped: details.append("当前实现仍带有未完成分支。") if summary is None: summary = "执行该公开方法对应的当前实现。" return ImplementationFact(summary=summary, details=details or [summary]) def dedupe_lines(lines: list[str]) -> list[str]: result: list[str] = [] seen: set[str] = set() for line in lines: if line in seen: continue seen.add(line) result.append(line) return result def analyze_method_group( class_name: str, method_name: str, overloads: list[dict[str, object]], header_text: str, source_text: str, source_rel: str | None, ) -> ImplementationFact: implementation_blocks = extract_qualified_blocks(source_text, class_name, method_name) if not implementation_blocks: implementation_blocks = extract_inline_blocks(header_text, method_name) details: list[str] = [] summaries: list[str] = [] for overload in overloads: suffix = str(overload.get("suffix", "")).strip() if "= 0" in suffix: summaries.append("纯虚接口。") details.append("该声明是纯虚接口，基类不提供实现。") for block in implementation_blocks: if block.kind == "default": if method_name == class_name: summaries.append(f"构造 `{class_name}` 实例。") details.append("当前为默认构造实现。") elif method_name == f"~{class_name}": summaries.append(f"销毁 `{class_name}` 实例。") details.append("当前为默认析构实现。") else: details.append("当前为 `= default` 实现。") continue if block.kind == "delete": details.append("当前声明为 `= delete`。") continue fact = analyze_complex_body(block.body) if fact.summary: summaries.append(fact.summary) details.extend(fact.details) if not details and source_rel: details.append(f"具体定义位于 `{source_rel}`。") short_desc = next((item for item in summaries if item), None) if short_desc is None: if method_name == class_name: short_desc = f"构造 `{class_name}` 实例。" elif method_name == f"~{class_name}": short_desc = f"销毁 `{class_name}` 实例。" elif method_name.startswith("Get"): short_desc = f"返回 `{camel_tail(method_name, 3)}` 相关结果。" elif method_name.startswith("Set"): short_desc = f"更新 `{camel_tail(method_name, 3)}` 相关状态。" elif method_name.startswith("Is"): short_desc = f"判断 `{camel_tail(method_name, 2)}` 条件是否成立。" elif method_name.startswith("Has"): short_desc = f"判断是否具备 `{camel_tail(method_name, 3)}`。" elif method_name.startswith("Can"): short_desc = f"判断当前是否可以执行 `{camel_tail(method_name, 3)}`。" elif method_name.startswith("Load"): short_desc = f"执行 `{method_name}` 加载流程。" elif method_name.startswith("Create"): short_desc = f"执行 `{method_name}` 创建流程。" elif method_name.startswith("Update"): short_desc = f"执行一次 `{method_name}` 更新。" else: short_desc = f"执行 `{method_name}` 对应的公开操作。" if not details: details.append(short_desc) return ImplementationFact(summary=short_desc, details=dedupe_lines(details)) def build_method_page( class_name: str, namespace: str, relative_header: str, group: dict[str, object], analysis: ImplementationFact, ) -> str: label = str(group["label"]) method_name = str(group["method_name"]) overloads: list[dict[str, object]] = group["overloads"] # type: ignore[assignment] lines: list[str] = [] lines.append(f"# {class_name}::{label}") lines.append("") lines.append(f"**命名空间**: `{namespace}`") lines.append("") lines.append("**类型**: `method`") lines.append("") lines.append(f"**头文件**: `{relative_header}`") lines.append("") lines.append("## 签名") lines.append("") lines.append("```cpp") for overload in overloads: lines.append(f"{overload['signature']};") lines.append("```") lines.append("") lines.append("## 作用") lines.append("") lines.append(analysis.summary) lines.append("") lines.append("## 当前实现") lines.append("") for detail in analysis.details: lines.append(f"- {detail}") lines.append("") lines.append("## 相关文档") lines.append("") lines.append(f"- [{class_name}]({class_name}.md)") if method_name.startswith("Get") and any(str(item["file_name"]) == f"Set{method_name[3:]}" for item in group.get("siblings", [])): # type: ignore[operator] lines.append(f"- [Set{method_name[3:]}](Set{method_name[3:]}.md)") elif method_name.startswith("Set") and any(str(item["file_name"]) == f"Get{method_name[3:]}" for item in group.get("siblings", [])): # type: ignore[operator] lines.append(f"- [Get{method_name[3:]}](Get{method_name[3:]}.md)") return "\n".join(lines).rstrip() + "\n" def rebuild_method_table( content: str, method_groups: list[dict[str, object]], analyses: dict[str, ImplementationFact], ) -> str: if "## 公共方法" not in content: return content lines = ["## 公共方法", "", "| 方法 | 描述 |", "|------|------|"] for group in method_groups: file_name = str(group["file_name"]) label = str(group["label"]) description = analyses[file_name].summary lines.append(f"| [{label}]({file_name}.md) | {description} |") section = "\n".join(lines) + "\n" return METHOD_SECTION_RE.sub(section, content) def main() -> int: rewritten_method_pages = 0 rewritten_overviews = 0 for header_path in sorted(INCLUDE_ROOT.rglob("*.h")): relative_header = header_path.relative_to(INCLUDE_ROOT.parent).as_posix() relative_source = header_path.relative_to(INCLUDE_ROOT).with_suffix(".cpp") source_path = REPO_ROOT / "engine" / "src" / relative_source source_text = source_path.read_text(encoding="utf-8", errors="ignore") if source_path.exists() else "" source_rel = source_path.relative_to(REPO_ROOT).as_posix() if source_path.exists() else None header_text = header_path.read_text(encoding="utf-8", errors="ignore") lines = header_text.splitlines() declarations = find_declarations(lines, build_namespace_map(lines)) primary = select_primary(header_path.stem, declarations) if primary is None or not primary.methods: continue doc_dir = DOC_ROOT / "XCEngine" / header_path.parent.relative_to(INCLUDE_ROOT) / header_path.stem if not doc_dir.exists(): continue method_groups = group_methods(primary.methods, primary.name) analyses: dict[str, ImplementationFact] = {} for group in method_groups: group["siblings"] = method_groups analyses[str(group["file_name"])] = analyze_method_group( primary.name, str(group["method_name"]), group["overloads"], # type: ignore[arg-type] header_text, source_text, source_rel, ) overview_path = doc_dir / f"{header_path.stem}.md" if overview_path.exists(): overview_content = overview_path.read_text(encoding="utf-8") if has_any_token(overview_content, TEMPLATE_TABLE_TOKENS) or has_generic_fallback(overview_content): updated = rebuild_method_table(overview_content, method_groups, analyses) if updated != overview_content: overview_path.write_text(updated, encoding="utf-8") rewritten_overviews += 1 for group in method_groups: file_name = str(group["file_name"]) page_path = doc_dir / f"{file_name}.md" if not page_path.exists(): continue content = page_path.read_text(encoding="utf-8") if not has_any_token(content, TEMPLATE_METHOD_TOKENS) and not has_generic_fallback(content): continue updated = build_method_page( primary.name, primary.namespace, relative_header, group, analyses[file_name], ) if updated != content: page_path.write_text(updated, encoding="utf-8") rewritten_method_pages += 1 print(f"Rewritten overview pages: {rewritten_overviews}") print(f"Rewritten method pages: {rewritten_method_pages}") return 0 if __name__ == "__main__": raise SystemExit(main())