From e8d33494e49b87f7e6551678d25103d38366f9c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Fr=C3=A8rejean?= Date: Sat, 30 May 2026 13:24:15 +0200 Subject: [PATCH] docs: trim comments to non-obvious WHY only Remove docblocks that restated the type name (WHAT) or duplicated a governing ADR, and strip ADR/tooling-enforced clauses (e.g. worker-mode call-time resolution, already covered by ADR-0007 and the Igor CI check). Keep only comments carrying non-obvious WHY: the AbstractAuditEvent extension seam, AuditQuery AND-combination, RecordReader actors() rationale, NewAuditRecord write/read disambiguation, and the resolver role lines. --- src/Event/AbstractAuditEvent.php | 6 +++--- src/Event/AuditEvent.php | 4 ---- src/Event/Changeset.php | 4 ---- src/Event/FieldChange.php | 4 ---- src/Event/RenderLine.php | 3 --- src/Event/RenderPayload.php | 4 ---- src/Event/Subject.php | 3 --- src/Reading/AuditActor.php | 3 --- src/Reading/AuditEntry.php | 4 ---- src/Reading/AuditPage.php | 3 --- src/Reading/AuditQuery.php | 3 +-- src/Reading/RecordReader.php | 4 ++-- src/Record/AuditRecord.php | 4 ---- src/Recording/Actor.php | 3 --- src/Recording/ActorResolver.php | 3 +-- src/Recording/DefaultRecorder.php | 4 ---- src/Recording/IdentityGenerator.php | 3 --- src/Recording/NewAuditRecord.php | 3 +-- src/Recording/Origin.php | 3 --- src/Recording/OriginResolver.php | 2 +- src/Recording/RecordStore.php | 3 --- src/Recording/Recorder.php | 4 ---- src/Recording/SubjectLabeller.php | 5 ++--- 23 files changed, 11 insertions(+), 71 deletions(-) diff --git a/src/Event/AbstractAuditEvent.php b/src/Event/AbstractAuditEvent.php index 4eddca7..ca71265 100644 --- a/src/Event/AbstractAuditEvent.php +++ b/src/Event/AbstractAuditEvent.php @@ -7,9 +7,9 @@ use Override; /** - * Base for concrete audit events. A subclass must implement code(); everything - * else has a safe default. Override parameters()/additionalInfo() to shape the - * frozen render payload, and subject()/changes()/data() to add detail. + * A subclass need only implement code(); every other method has a safe default. + * Override messageKey()/parameters()/additionalInfo() to shape what is rendered, + * and subject()/changes()/data() to add detail. */ abstract readonly class AbstractAuditEvent implements AuditEvent { diff --git a/src/Event/AuditEvent.php b/src/Event/AuditEvent.php index 182a336..7c2e186 100644 --- a/src/Event/AuditEvent.php +++ b/src/Event/AuditEvent.php @@ -4,10 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * The domain's account of an auditable act. Pure: no clock, no identity, no - * services. The recorder freezes its output at the moment of the act. - */ interface AuditEvent { public function code(): string; diff --git a/src/Event/Changeset.php b/src/Event/Changeset.php index e76e48f..426b04c 100644 --- a/src/Event/Changeset.php +++ b/src/Event/Changeset.php @@ -4,10 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * Frozen, curated field-level diff: the "what changed" of an auditable act. - * Pure structural data — reconstructable from JSON without any producing class. - */ final readonly class Changeset { /** @var list */ diff --git a/src/Event/FieldChange.php b/src/Event/FieldChange.php index 92b4e93..007736f 100644 --- a/src/Event/FieldChange.php +++ b/src/Event/FieldChange.php @@ -4,10 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * One field's before/after. The domain curates which fields are recorded; - * sensitive fields are recorded as changed without their values (redacted). - */ final readonly class FieldChange { private function __construct( diff --git a/src/Event/RenderLine.php b/src/Event/RenderLine.php index 93ccdb7..63b3c3e 100644 --- a/src/Event/RenderLine.php +++ b/src/Event/RenderLine.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * A single translatable line: a key plus its frozen parameters. - */ final readonly class RenderLine { /** @param array $parameters */ diff --git a/src/Event/RenderPayload.php b/src/Event/RenderPayload.php index dca3118..1e700c1 100644 --- a/src/Event/RenderPayload.php +++ b/src/Event/RenderPayload.php @@ -4,10 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * Frozen render tree: translation inputs captured at the moment of the act — - * never a live object, never a pre-rendered string. - */ final readonly class RenderPayload { /** @param list $info */ diff --git a/src/Event/Subject.php b/src/Event/Subject.php index 400f0e7..7e61852 100644 --- a/src/Event/Subject.php +++ b/src/Event/Subject.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Event; -/** - * A reference to the audited entity: its class and identifier. Never its state. - */ final readonly class Subject { /** @param class-string $class */ diff --git a/src/Reading/AuditActor.php b/src/Reading/AuditActor.php index e89458d..3767738 100644 --- a/src/Reading/AuditActor.php +++ b/src/Reading/AuditActor.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Reading; -/** - * Distinct actor as seen in the trail, for building filter option lists. - */ final readonly class AuditActor { public function __construct( diff --git a/src/Reading/AuditEntry.php b/src/Reading/AuditEntry.php index ceb8ea7..1706e8d 100644 --- a/src/Reading/AuditEntry.php +++ b/src/Reading/AuditEntry.php @@ -10,10 +10,6 @@ use WeDevelop\AuditLog\Event\RenderPayload; use WeDevelop\AuditLog\Record\AuditRecord; -/** - * A detached, immutable view of a stored record returned by the reader. Safe to - * pass around: carries no persistence handle. - */ final readonly class AuditEntry implements AuditRecord { /** @param array|null $data */ diff --git a/src/Reading/AuditPage.php b/src/Reading/AuditPage.php index bdf7825..82e2f04 100644 --- a/src/Reading/AuditPage.php +++ b/src/Reading/AuditPage.php @@ -8,9 +8,6 @@ use function sprintf; -/** - * A page of audit entries plus the metadata needed to paginate. - */ final readonly class AuditPage { public int $pageCount; diff --git a/src/Reading/AuditQuery.php b/src/Reading/AuditQuery.php index 8d65521..90dd6bf 100644 --- a/src/Reading/AuditQuery.php +++ b/src/Reading/AuditQuery.php @@ -11,8 +11,7 @@ use function sprintf; /** - * Filter and pagination criteria for reading the trail. All filters are - * optional and combine with AND. + * All filters are optional and combine with AND. */ final readonly class AuditQuery { diff --git a/src/Reading/RecordReader.php b/src/Reading/RecordReader.php index c6c596e..180dc49 100644 --- a/src/Reading/RecordReader.php +++ b/src/Reading/RecordReader.php @@ -5,8 +5,8 @@ namespace WeDevelop\AuditLog\Reading; /** - * Reads the trail: a filtered, paginated page of entries, and the distinct - * actors present (for filter option lists). + * actors() returns the distinct actors present in the trail, for building + * filter option lists. */ interface RecordReader { diff --git a/src/Record/AuditRecord.php b/src/Record/AuditRecord.php index f2bbaec..15429c6 100644 --- a/src/Record/AuditRecord.php +++ b/src/Record/AuditRecord.php @@ -9,10 +9,6 @@ use WeDevelop\AuditLog\Event\Changeset; use WeDevelop\AuditLog\Event\RenderPayload; -/** - * The immutable read shape of a stored record. No mutators anywhere: a record - * never changes after it is written. - */ interface AuditRecord { public string $id { get; } diff --git a/src/Recording/Actor.php b/src/Recording/Actor.php index 0365aa0..940b12a 100644 --- a/src/Recording/Actor.php +++ b/src/Recording/Actor.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Recording; -/** - * The acting principal, frozen at the moment: a stable id plus a display label. - */ final readonly class Actor { public function __construct( diff --git a/src/Recording/ActorResolver.php b/src/Recording/ActorResolver.php index d1fe2ae..d9a883b 100644 --- a/src/Recording/ActorResolver.php +++ b/src/Recording/ActorResolver.php @@ -5,8 +5,7 @@ namespace WeDevelop\AuditLog\Recording; /** - * Resolves the acting principal from ambient state. Implementations MUST read - * the principal live, at call time (worker mode); they capture no state. + * Resolves the acting principal from ambient state. */ interface ActorResolver { diff --git a/src/Recording/DefaultRecorder.php b/src/Recording/DefaultRecorder.php index 807d1c0..8e85755 100644 --- a/src/Recording/DefaultRecorder.php +++ b/src/Recording/DefaultRecorder.php @@ -9,10 +9,6 @@ use WeDevelop\AuditLog\Event\AuditEvent; use WeDevelop\AuditLog\Event\ProvidesSubjectLabel; -/** - * The moment, made concrete: resolves the ambient strands (time, actor, origin, - * subject label), freezes them with the event's domain facts, and appends once. - */ final readonly class DefaultRecorder implements Recorder { public function __construct( diff --git a/src/Recording/IdentityGenerator.php b/src/Recording/IdentityGenerator.php index 4b5b934..d8189d3 100644 --- a/src/Recording/IdentityGenerator.php +++ b/src/Recording/IdentityGenerator.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Recording; -/** - * Generates the identifier for a new record. - */ interface IdentityGenerator { public function next(): string; diff --git a/src/Recording/NewAuditRecord.php b/src/Recording/NewAuditRecord.php index 3c34d50..113bfbb 100644 --- a/src/Recording/NewAuditRecord.php +++ b/src/Recording/NewAuditRecord.php @@ -10,8 +10,7 @@ use WeDevelop\AuditLog\Event\RenderPayload; /** - * The frozen result the recorder assembles and hands to the store. Write-input - * only; the durable read shape is Record\AuditRecord. + * Write-input only; the durable read shape is Record\AuditRecord. */ final readonly class NewAuditRecord { diff --git a/src/Recording/Origin.php b/src/Recording/Origin.php index 39a9071..e3e427b 100644 --- a/src/Recording/Origin.php +++ b/src/Recording/Origin.php @@ -6,9 +6,6 @@ use WeDevelop\AuditLog\Event\AuditChannel; -/** - * Where the act entered the system: the channel and the network address. - */ final readonly class Origin { public function __construct( diff --git a/src/Recording/OriginResolver.php b/src/Recording/OriginResolver.php index 3f2479d..91e4691 100644 --- a/src/Recording/OriginResolver.php +++ b/src/Recording/OriginResolver.php @@ -6,7 +6,7 @@ /** * Resolves the channel and network address of the act from the runtime - * entrypoint, live at call time. + * entrypoint. */ interface OriginResolver { diff --git a/src/Recording/RecordStore.php b/src/Recording/RecordStore.php index b60b33b..63336a6 100644 --- a/src/Recording/RecordStore.php +++ b/src/Recording/RecordStore.php @@ -4,9 +4,6 @@ namespace WeDevelop\AuditLog\Recording; -/** - * Appends a record to the trail. Append-only: there is no update or delete. - */ interface RecordStore { public function add(NewAuditRecord $record): void; diff --git a/src/Recording/Recorder.php b/src/Recording/Recorder.php index 133806d..48345e2 100644 --- a/src/Recording/Recorder.php +++ b/src/Recording/Recorder.php @@ -6,10 +6,6 @@ use WeDevelop\AuditLog\Event\AuditEvent; -/** - * The single write seam: captures the moment of an auditable act and appends a - * frozen record. - */ interface Recorder { public function record(AuditEvent $event): void; diff --git a/src/Recording/SubjectLabeller.php b/src/Recording/SubjectLabeller.php index 1f94196..b620b4a 100644 --- a/src/Recording/SubjectLabeller.php +++ b/src/Recording/SubjectLabeller.php @@ -7,9 +7,8 @@ use WeDevelop\AuditLog\Event\Subject; /** - * Produces a display label for the live subject, snapshotted at the moment so - * the trail stays readable after the subject is deleted. Returns null when no - * label can be resolved. + * Snapshots a display label for the subject at record time, so the trail + * survives the subject's deletion. */ interface SubjectLabeller {