sindoring/open-wc

Fork 0

Files

T

sindoring fbe22f6a94 ещё обновление доки

2026-07-10 18:29:56 +04:00

12 KiB

Raw Blame History

OpenWC Documentation Standard

Цель

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

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

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

Правила именования, KISS и локализации неизбежной сложности определены в CODING_STANDARD.md. Документация и ясные имена дополняют друг друга: комментарий не должен компенсировать неудачное имя.

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

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.

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

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

Metadata/status.
Purpose и non-goals.
Context и architecture boundaries.
Public API.
Inputs и outputs.
Data flow diagram.
State/lifecycle или sequence diagram, если применимо.
Ownership, threading и resource lifetime.
Errors, cancellation и recovery.
Configuration/capabilities/profiles.
Persistence/cache/migrations.
Diagnostics и observability.
Tests, fidelity evidence и performance budgets.
Extension points.
Known gaps.
Source map.

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

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

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

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

Data flow diagram

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

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.

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:

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.

12 KiB Raw Blame History Unescape Escape