docs: trim comments to non-obvious WHY only

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
 {

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;

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<FieldChange> */

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(

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<string, scalar> $parameters */

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<RenderLine> $info */

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 */

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(

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<string, mixed>|null $data */

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;

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
 {

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
 {

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; }

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(

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
 {

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(

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;

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
 {

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(

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
 {

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;

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;

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
 {