Pierre-Marie Charavel
93ca33c36a
- ue_parser.py: position-based UE C++ header parser - ue_markdown.py: compact agent-optimised Markdown renderer - generate.py: two-pass CLI (parse-all → type index → render-all) - samples/: representative UE headers (GeomUtils, AIController, GameplayTagsManager) - .claude/skills/ue-api/: Claude Code skill for querying UE docs + source headers - CLAUDE.md: architecture notes, usage, critical gotchas Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
50 lines
2.9 KiB
Markdown
50 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Purpose
|
|
|
|
UnrealDocGenerator is a tool (in development) for generating documentation from Unreal Engine C++ header files. The `samples/` directory contains representative Unreal Engine headers used as test inputs:
|
|
|
|
- `samples/GeomUtils.h` — Small utility header (~6 KB): geometry/math helpers in `UE::AI` namespace
|
|
- `samples/AIController.h` — Medium header (~22 KB): `AAIController` class with movement, behavior tree, perception, and blackboard integration
|
|
- `samples/GameplayTagsManager.h` — Large/complex header (~43 KB): `UGameplayTagsManager` singleton with tag trees, INI/DataTable loading, and editor support
|
|
|
|
These samples cover a range of complexity (free functions, large classes, deeply nested types, macros, delegates) suitable for stress-testing a parser or doc generator.
|
|
|
|
## Current State
|
|
|
|
Implementation complete. Three Python files:
|
|
- `ue_parser.py` — Parses UE headers into dataclasses
|
|
- `ue_markdown.py` — Renders parsed data as Markdown (ultra-compact format, documented items only)
|
|
- `generate.py` — CLI entry point; two-pass pipeline (parse-all → build type index → render-all)
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python generate.py samples/ docs/ # process directory → docs/
|
|
python generate.py samples/AIController.h docs/ # single file
|
|
```
|
|
|
|
Output: one `.md` per `.h` + `docs/type-index.txt` (compact `TypeName: path/to/File.md` lookup).
|
|
|
|
Agent lookup pattern: `grep "^AController:" docs/type-index.txt` → instant single-line result.
|
|
|
|
## Architecture Notes
|
|
|
|
- Parser uses a **position-based scanner**, not line-by-line regex, to handle nested braces correctly.
|
|
- `find_matching_close()` extracts balanced `{}`/`()` while skipping `//`, `/* */`, and string literals.
|
|
- Only items with actual C++ doc comments (`/** */`) are included in output (`_has_doc()` filter).
|
|
- Two-pass pipeline in `generate.py`: Pass 1 parses all files, Pass 2 renders with cross-reference links.
|
|
- Inline cross-references: base class names linked to their `.md` when in corpus (`_make_type_link()`).
|
|
- No "See also" section — inline links in `*Inherits*:` lines cover cross-file navigation.
|
|
- Deprecated functions excluded from output (`not f.is_deprecated` in visibility filter).
|
|
- Enums with no value descriptions use compact inline format (`Values: A, B, C`) instead of a table.
|
|
- Placeholder descriptions (`------//`) filtered by `_PLACEHOLDER_RE` in `_fn_body()`.
|
|
|
|
## Critical Gotchas
|
|
|
|
- **Never** use `\s` inside a `[...]` character class with `*?` on C++ source — causes catastrophic regex backtracking (hangs on `AIController.h`). Use line-based scanning instead.
|
|
- Identifier regex must be `r'\w+'`, **not** `r'[\w:~]+'` — the latter consumes `public:` as one token, breaking access specifier detection (all members become `private`).
|
|
- Module name casing: use `_caps_to_camel()` (not `.title()`) — `AIMODULE.title()` → `Aimodule` instead of `AIModule`.
|