крупное обновление документации
This commit is contained in:
@@ -0,0 +1,278 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user