279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
# 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`.
|