# OpenWC Documentation Standard

## Цель

Документация является частью реализации. Код без актуального объяснения публичного API, данных, ownership и поведения считается незавершённым, даже если компилируется и проходит тесты.

Документация должна позволить человеку ответить:

- зачем существует модуль;
- какие данные он получает и откуда;
- что он создаёт или изменяет;
- кто владеет состоянием и ресурсами;
- какие зависимости допустимы;
- что происходит по шагам;
- как модуль завершается, отменяется и восстанавливается после ошибки;
- как проверить fidelity, correctness и performance;
- какие части реализованы, запланированы или известны как gap.

## Уровни документации

### 1. Inline API documentation

Находится рядом с кодом и является источником истины для точной сигнатуры:

- публичные classes/interfaces;
- public methods/functions;
- signals/events;
- exported properties/configuration;
- commands, events и read models;
- ownership/lifetime/threading requirements;
- error/return semantics;
- non-obvious invariants.

### 2. Module specification

Находится в `docs/modules/<module>.md` и объясняет назначение, архитектуру, data flow, state/lifecycle, extension points и verification. Шаблон: [`modules/TEMPLATE.md`](modules/TEMPLATE.md).

### 3. Data/schema documentation

Описывает persisted/wire/content formats: fields, types, units, optionality, version, migration, provenance и compatibility. Нельзя объяснять schema только примером JSON или SQL.

### 4. ADR

Фиксирует значимое решение, варианты и последствия. ADR не заменяет актуальное описание модуля: после решения module spec обновляется до текущего состояния.

### 5. Operational documentation

Команды build/test/import/bake/deploy/recovery, expected outputs и diagnostics. Команда без условий запуска и интерпретации результата недостаточна.

## Обязательная module specification

Новый самостоятельный модуль или существенно выделенная подсистема обязаны иметь документ со следующими разделами:

1. Metadata/status.
2. Purpose и non-goals.
3. Context и architecture boundaries.
4. Public API.
5. Inputs и outputs.
6. Data flow diagram.
7. State/lifecycle или sequence diagram, если применимо.
8. Ownership, threading и resource lifetime.
9. Errors, cancellation и recovery.
10. Configuration/capabilities/profiles.
11. Persistence/cache/migrations.
12. Diagnostics и observability.
13. Tests, fidelity evidence и performance budgets.
14. Extension points.
15. Known gaps.
16. Source map.

`Status` принимает только:

- `Planned`;
- `Prototype`;
- `Partial`;
- `Implemented`;
- `Verified`;
- `Deprecated`.

`Implemented` не означает fidelity; `Verified` требует evidence и ссылок на тесты.

## Обязательные схемы

### Data flow diagram

Обязательна для каждого module spec. Показывает реальные имена contracts и направление данных:

```mermaid
flowchart LR
    Source[ADT bytes] --> Parser[ADTLoader]
    Parser --> Data[AdtTileData]
    Data --> Planner[StreamingTargetPlanner]
    Planner --> Queue[RenderFinalizeCommand]
    Queue --> Renderer[TerrainRenderer]
```

Диаграмма должна показывать:

- внешние источники;
- входные contracts;
- преобразования;
- выходные contracts/side effects;
- persistence/cache, если участвует;
- запрещённое направление, если оно является важной границей.

### Sequence diagram

Обязательна, если операция пересекает два и более из следующих boundary:

- thread/job queue;
- network;
- gameplay;
- renderer/UI/audio;
- Editor;
- server/database;
- filesystem/build pipeline.

```mermaid
sequenceDiagram
    participant Net as WorldSession
    participant Game as WorldState
    participant View as EntityPresenter
    participant Render as WorldRenderFacade
    Net->>Game: EntityCreated
    Game-->>View: EntityReadModel change
    View->>Render: spawn_entity(descriptor)
```

### State diagram

Обязательна для lifecycle/state machine с тремя и более состояниями, reconnect/retry или rollback:

```mermaid
stateDiagram-v2
    [*] --> Disconnected
    Disconnected --> Connecting
    Connecting --> Authenticated
    Connecting --> Failed
    Authenticated --> Disconnected
    Failed --> Connecting: retry
```

### Dependency diagram

Обязательна при изменении архитектурной границы или модуле с тремя и более downstream consumers. Она показывает compile/runtime dependencies, а не случайное расположение Node в сцене.

## Public API documentation

Для каждого public symbol указываются:

- краткое назначение;
- параметры с единицами и coordinate space;
- return value или emitted event;
- preconditions/postconditions;
- ownership и mutability;
- допустимый thread;
- failure behavior;
- profile/capability restrictions;
- пример только если контракт остаётся неочевидным.

### GDScript

- Использовать `##` documentation comments для class, public methods, signals и exported properties.
- Всегда указывать типы аргументов/return, где Godot API позволяет.
- `@export` property объясняет units/range/profile и runtime mutability.
- Signal документирует момент emission, arguments и ordering guarantees.
- Internal helper получает комментарий, если содержит сложный invariant, coordinate conversion, ownership или performance assumption.

### C++/GDExtension

- Public headers используют Doxygen-compatible `///`/`/** */`.
- Документировать ownership указателей/references/buffers, thread safety и error transport.
- Binary structs указывают source format/build, packing/endianness и validation.
- Native/Godot boundary описывает allocation и lifetime Variant/PackedArray/Resource.
- Implementation comments объясняют `why` и invariant, а не пересказывают строку кода.

### Shaders/materials

- Uniform/global parameter: coordinate/color space, range, units и producer.
- Material profile: supported WoW shader/blend modes и approximations.
- Expensive branch/texture dependency имеет cost/fallback note.
- Blizzlike и Enhanced behavior документируются отдельно.

### Network codecs

- Opcode/direction/session phase.
- Exact build/profile.
- Field order/type/endianness/conditional presence.
- Domain events на выходе.
- Malformed/unknown handling.
- Fixture/reference source без sensitive payload.

### Content/server schemas

- Canonical field и mapping на каждый core adapter.
- Unit, default, null/optional semantics и flags.
- Numeric ID allocation и references.
- Migration/rollback и unsupported degradation.

## Документация потока данных

Inputs/outputs оформляются таблицей:

| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|---|---|---|---|---|---|
| Input | `EntityMoved` | `WorldSession` | `WorldState` | Immutable event | Game-thread apply |
| Output | `EntityReadModel` | `WorldState` | Presenter/UI | Snapshot | Until next revision |

Side effects перечисляются отдельно:

- scene tree mutation;
- RenderingServer RID creation/free;
- filesystem/cache write;
- network send;
- DB query/apply;
- settings/SavedVariables mutation.

Скрытый side effect является дефектом документации и API.

## Статус реализации

Документ не должен выдавать roadmap за существующий код. Каждый важный capability помечается:

| Capability | Status | Evidence | Gap/next step |
|---|---|---|---|

После изменения кода статус и `Last verified` обновляются в том же work package. Если документацию нельзя подтвердить, ставится `Unknown`/`Planned`, а не предположение.

## Documentation change rules

Документация обновляется в том же work package, если изменились:

- public API/signal/event;
- data flow или ownership;
- state/lifecycle;
- thread boundary;
- format/schema/cache version;
- configuration/capability;
- diagnostics/error/recovery;
- fidelity или performance behavior;
- extension point.

Переименование symbol/path требует обновить source map, diagrams и ссылки. Stale documentation считается regression.

## Code comments

Хороший комментарий объясняет:

- почему решение отличается от очевидного;
- форматное или protocol ограничение;
- ownership/thread invariant;
- причину batching/budget;
- источник fidelity behavior;
- временный compatibility path и условие удаления.

Плохой комментарий:

- пересказывает код;
- обещает будущую работу без target/work package ID;
- содержит устаревшую сигнатуру;
- маскирует magic number без source/unit;
- утверждает `Blizzlike` без evidence.

TODO/FIXME должен содержать target/work package или diagnostic code.

## Review gate

Reviewer/integrator проверяет:

- public symbols имеют inline docs;
- module spec существует или обновлён;
- input/output и side effects перечислены;
- diagrams соответствуют реальным contracts;
- state/error/recovery paths показаны;
- tests/evidence и known gaps честны;
- документы не дублируют противоречивые источники истины.

Если хотя бы один обязательный пункт отсутствует, handoff остаётся `PARTIAL`, а target не может получить `DONE`.