docs: S23.10 add @file briefs to the Core/Interface headers

Core/Interface/ExternC.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The C-linkage guard macros (EXTERN_C_BEGIN / EXTERN_C_END) that wrap every
+ *  public header so a C++ consumer links the declarations with C linkage. */
 #ifndef EXTERNC_H
 #define EXTERNC_H
 

Core/Interface/SolidSyslog.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The application logging API: SolidSyslog_Log / _LogWithSd to emit an event,
+ *  SolidSyslog_Service to drive delivery, and the SolidSyslogMessage struct. */
 #ifndef SOLIDSYSLOG_H
 #define SOLIDSYSLOG_H
 

Core/Interface/SolidSyslogAddress.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The opaque resolved-destination handle a Resolver writes and a Datagram or
+ *  Stream reads; the concrete layout is private to each platform's sources. */
 #ifndef SOLIDSYSLOGADDRESS_H
 #define SOLIDSYSLOGADDRESS_H
 

Core/Interface/SolidSyslogAtomicCounter.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The atomic-counter role: hand out the next sequenceId (Increment), wrap-aware
+ *  over [1, 2^31 - 1] and never 0 per RFC 5424 §7.3.1. This call dispatches to
+ *  the injected counter's vtable, so behaviour is that counter's. */
 #ifndef SOLIDSYSLOGATOMICCOUNTER_H
 #define SOLIDSYSLOGATOMICCOUNTER_H
 

Core/Interface/SolidSyslogAtomicCounterDefinition.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The AtomicCounter vtable (Increment) — the contract an implementor fills in
+ *  (the AtomicCounter extension point). */
 #ifndef SOLIDSYSLOGATOMICCOUNTERDEFINITION_H
 #define SOLIDSYSLOGATOMICCOUNTERDEFINITION_H
 

Core/Interface/SolidSyslogBlockDevice.h

@@ -1,3 +1,8 @@
+/** @file
+ *  The block-device role: block-indexed storage (Acquire / Dispose / Exists /
+ *  Read / Append / WriteAt / Size / GetBlockSize) beneath a BlockStore. These
+ *  calls dispatch to the injected device's vtable, so behaviour is that
+ *  device's. */
 #ifndef SOLIDSYSLOGBLOCKDEVICE_H
 #define SOLIDSYSLOGBLOCKDEVICE_H
 

Core/Interface/SolidSyslogBlockDeviceDefinition.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The BlockDevice vtable (Acquire / Dispose / Exists / Read / Append / WriteAt /
+ *  Size / GetBlockSize) — the contract an implementor fills in (the BlockDevice
+ *  extension point). */
 #ifndef SOLIDSYSLOGBLOCKDEVICEDEFINITION_H
 #define SOLIDSYSLOGBLOCKDEVICEDEFINITION_H
 

Core/Interface/SolidSyslogBlockStore.h

@@ -1,3 +1,24 @@
+/** @file
+ *  A store-and-forward Store backed by a BlockDevice: records are appended to
+ *  the current write block, and once a block fills the write rolls to the next,
+ *  giving durable retention across a restart. Create resumes from whatever
+ *  records are already on the device (scanning the read block, honouring any
+ *  per-record integrity trailer from the injected SecurityPolicy) so a reboot
+ *  keeps unsent records queued.
+ *
+ *  MaxBlocks caps retention; DiscardPolicy governs the overflow once every block
+ *  is full — Oldest evicts the oldest block to keep accepting writes, Newest
+ *  refuses the incoming record, Halt refuses it, latches (IsHalted stops
+ *  Service), and fires OnStoreFull once. An optional capacity-threshold function
+ *  (queried each Write) drives an edge-triggered OnThresholdCrossed callback for
+ *  early back-pressure signalling. Mind the recursion gotcha: under a
+ *  PassthroughBuffer, SolidSyslog_Log sends inline, so logging from the
+ *  threshold callback re-enters Write — drive the logger from a returning Buffer
+ *  or gate the Log instead.
+ *
+ *  Internally each pool slot composes an inner RecordStore over a BlockSequence,
+ *  both drawn from sibling pools; a block too small for one worst-case record is
+ *  grown to fit and reported as a WARNING rather than failing Create. */
 #ifndef SOLIDSYSLOGBLOCKSTORE_H
 #define SOLIDSYSLOGBLOCKSTORE_H
 

Core/Interface/SolidSyslogBlockStoreErrors.h

@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the BlockStore. */
 #ifndef SOLIDSYSLOGBLOCKSTOREERRORS_H
 #define SOLIDSYSLOGBLOCKSTOREERRORS_H
 

Core/Interface/SolidSyslogBuffer.h

@@ -1,3 +1,8 @@
+/** @file
+ *  The buffer role: producer Write / consumer Read that decouples
+ *  SolidSyslog_Log from Service. These calls dispatch to the injected buffer's
+ *  vtable, so behaviour — notably whether Write blocks or returns at once — is
+ *  that buffer's. */
 #ifndef SOLIDSYSLOGBUFFER_H
 #define SOLIDSYSLOGBUFFER_H
 

Core/Interface/SolidSyslogBufferCategories.h

@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the Buffer role:
+ *  SOLIDSYSLOG_CAT_BUFFER_BACKEND_FAILED. */
 #ifndef SOLIDSYSLOGBUFFERCATEGORIES_H
 #define SOLIDSYSLOGBUFFERCATEGORIES_H
 

Core/Interface/SolidSyslogBufferDefinition.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The Buffer vtable (Write / Read) — the contract an implementor fills in (the
+ *  Buffer extension point). */
 #ifndef SOLIDSYSLOGBUFFERDEFINITION_H
 #define SOLIDSYSLOGBUFFERDEFINITION_H
 

Core/Interface/SolidSyslogCircularBuffer.h

@@ -1,3 +1,19 @@
+/** @file
+ *  An in-memory ring Buffer that decouples Log (enqueue) from Service (drain),
+ *  backed entirely by caller-supplied storage — no allocation of its own.
+ *
+ *  Records are framed with a uint16 length prefix and stored back-to-back. A
+ *  record is never split across the ring's end: one that would straddle the
+ *  wrap point is written whole to the front, leaving a gap that the reader skips
+ *  via a wrap marker. On a full ring the newest record is dropped (the write is
+ *  simply refused) rather than overwriting unsent data, so the oldest queued
+ *  records survive. A record larger than SOLIDSYSLOG_MAX_MESSAGE_SIZE is
+ *  rejected outright, and a Read whose buffer is too small for the head record
+ *  leaves the record in place and reports nothing delivered.
+ *
+ *  Every enqueue and drain is bracketed by the injected mutex, so the two sides
+ *  are safe on separate tasks; inject SolidSyslogNullMutex_Get() for single-task
+ *  use where the lock is pure overhead. */
 #ifndef SOLIDSYSLOGCIRCULARBUFFER_H
 #define SOLIDSYSLOGCIRCULARBUFFER_H
 

Core/Interface/SolidSyslogCircularBufferErrors.h

@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the CircularBuffer. */
 #ifndef SOLIDSYSLOGCIRCULARBUFFERERRORS_H
 #define SOLIDSYSLOGCIRCULARBUFFERERRORS_H
 

Core/Interface/SolidSyslogConfig.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The setup-time wiring: the SolidSyslogConfig struct and SolidSyslog_Create /
+ *  _Destroy that build and release a logger from it. */
 #ifndef SOLIDSYSLOGCONFIG_H
 #define SOLIDSYSLOGCONFIG_H
 

Core/Interface/SolidSyslogConfigLock.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The config-time critical-section injection pair guarding every pool
+ *  Create/Destroy slot-walk; the no-op default suits single-task setup. */
 #ifndef SOLIDSYSLOGCONFIGLOCK_H
 #define SOLIDSYSLOGCONFIGLOCK_H
 

Core/Interface/SolidSyslogCrc16.h

@@ -1,3 +1,8 @@
+/** @file
+ *  CRC-16/CCITT-FALSE checksum (poly 0x1021, init 0xFFFF, no reflection, no
+ *  final XOR; a.k.a. CRC-16/IBM-3740, check value 0x29B1). A pure function over
+ *  a byte range — no state, no lifecycle. Used by SolidSyslogCrc16Policy for an
+ *  unkeyed at-rest integrity trailer. */
 #ifndef SOLIDSYSLOGCRC16_H
 #define SOLIDSYSLOGCRC16_H
 

Core/Interface/SolidSyslogCrc16Policy.h

@@ -1,3 +1,13 @@
+/** @file
+ *  A SecurityPolicy that appends a two-byte CRC-16 trailer to each stored
+ *  record. Seal computes the CRC over the whole content; Open recomputes and
+ *  compares. This is an unkeyed checksum — it catches accidental corruption
+ *  (bit-rot, a truncated write) but is not tamper-evidence: anyone who edits a
+ *  record can recompute a matching CRC. For tamper-evidence or confidentiality
+ *  use a keyed policy. Being a checksum (not an AEAD), it ignores the record's
+ *  header/body split and checks the whole content as one span. The instance is
+ *  a shared stateless singleton, so it holds no pool slot and Destroy is a
+ *  no-op. */
 #ifndef SOLIDSYSLOGCRC16POLICY_H
 #define SOLIDSYSLOGCRC16POLICY_H
 

Core/Interface/SolidSyslogDatagram.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The datagram role: connectionless send of one message to an address (Open /
+ *  SendTo / Close), with a path-MTU hint (MaxPayload). These calls dispatch to
+ *  the injected datagram's vtable, so behaviour is that datagram's. */
 #ifndef SOLIDSYSLOGDATAGRAM_H
 #define SOLIDSYSLOGDATAGRAM_H
 

Core/Interface/SolidSyslogDatagramDefinition.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The Datagram vtable (Open / SendTo / MaxPayload / Close) — the unconnected
+ *  (UDP) transport contract an implementor fills in (the Datagram extension
+ *  point). */
 #ifndef SOLIDSYSLOGDATAGRAMDEFINITION_H
 #define SOLIDSYSLOGDATAGRAMDEFINITION_H
 

Core/Interface/SolidSyslogEndpoint.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The destination a sender is directed at (host sink + port) and the callbacks
+ *  a sender uses to pull it and to detect when it changes. */
 #ifndef SOLIDSYSLOGENDPOINT_H
 #define SOLIDSYSLOGENDPOINT_H
 

Core/Interface/SolidSyslogEndpointHost.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The value sink an endpoint callback writes the destination host into —
+ *  copied verbatim so a DNS name or IP literal reaches the resolver intact. */
 #ifndef SOLIDSYSLOGENDPOINTHOST_H
 #define SOLIDSYSLOGENDPOINTHOST_H
 

Core/Interface/SolidSyslogError.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The error-reporting API: SolidSyslog_SetErrorHandler to install a handler,
+ *  SolidSyslog_Error to emit, and the event's Severity / Source / Category /
+ *  Detail axes a handler reads. */
 #ifndef SOLIDSYSLOGERROR_H
 #define SOLIDSYSLOGERROR_H
 

Core/Interface/SolidSyslogErrorCategory.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The portable error-category axis: the universal lifecycle category macros
+ *  and the per-role base ranges a handler switches on or an emit site picks. */
 #ifndef SOLIDSYSLOGERRORCATEGORY_H
 #define SOLIDSYSLOGERRORCATEGORY_H
 

Core/Interface/SolidSyslogErrors.h

@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the SolidSyslog instance. */
 #ifndef SOLIDSYSLOGERRORS_H
 #define SOLIDSYSLOGERRORS_H
 

Core/Interface/SolidSyslogFile.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The file role: byte-file I/O (Open / Close / IsOpen / Read / Write / SeekTo /
+ *  Size / Truncate / Exists / Delete) backing the store. These calls dispatch to
+ *  the injected file's vtable, so behaviour is that file's. */
 #ifndef SOLIDSYSLOGFILE_H
 #define SOLIDSYSLOGFILE_H
 

Core/Interface/SolidSyslogFileBlockDevice.h

@@ -1,3 +1,17 @@
+/** @file
+ *  A BlockDevice that maps each block to its own file, named by a caller-given
+ *  prefix plus a two-digit block index and ".log" (block 0 is "<prefix>00.log").
+ *  The two-digit sequence caps the device at 100 blocks: an index above 99 is
+ *  rejected, which also stops a wide index being narrowed and aliasing an
+ *  existing block.
+ *
+ *  It caches a single open file handle and re-points it only when the addressed
+ *  block changes, so it upholds the one-open-handle-per-path invariant the
+ *  storage layer relies on and never leaves two handles racing on the same file.
+ *  Acquire opens (creating if needed) and truncates a block for fresh writes;
+ *  Append writes at end-of-file, WriteAt/Read seek to an explicit offset, and
+ *  Dispose deletes the block's file. GetBlockSize reports the configured
+ *  per-block capacity that a BlockStore reads once at construction. */
 #ifndef SOLIDSYSLOGFILEBLOCKDEVICE_H
 #define SOLIDSYSLOGFILEBLOCKDEVICE_H
 

Core/Interface/SolidSyslogFileBlockDeviceErrors.h

@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the FileBlockDevice. */
 #ifndef SOLIDSYSLOGFILEBLOCKDEVICEERRORS_H
 #define SOLIDSYSLOGFILEBLOCKDEVICEERRORS_H
 

Core/Interface/SolidSyslogFileDefinition.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The File vtable (Open / Close / IsOpen / Read / Write / SeekTo / Size /
+ *  Truncate / Exists / Delete) — the contract a porter fills in (the File
+ *  extension point). */
 #ifndef SOLIDSYSLOGFILEDEFINITION_H
 #define SOLIDSYSLOGFILEDEFINITION_H
 

Core/Interface/SolidSyslogHeaderField.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The value sink a callback writes an RFC 5424 header field (HOSTNAME /
+ *  APP-NAME / PROCID) into; the sink owns the charset and the field width. */
 #ifndef SOLIDSYSLOGHEADERFIELD_H
 #define SOLIDSYSLOGHEADERFIELD_H
 

Core/Interface/SolidSyslogHeaderFieldFunction.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The header-field callback typedef the integrator supplies to
+ *  SolidSyslogConfig for HOSTNAME / APP-NAME / PROCID. */
 #ifndef SOLIDSYSLOGHEADERFIELDFUNCTION_H
 #define SOLIDSYSLOGHEADERFIELDFUNCTION_H
 

Core/Interface/SolidSyslogKeyFunction.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The on-demand secret-key callback typedef the integrator supplies to a keyed
+ *  SecurityPolicy, so the key never lives on the policy instance. */
 #ifndef SOLIDSYSLOGKEYFUNCTION_H
 #define SOLIDSYSLOGKEYFUNCTION_H
 

Core/Interface/SolidSyslogMetaSd.h

@@ -1,3 +1,10 @@
+/** @file
+ *  A StructuredData source for the RFC 5424 §7.3 "meta" SD-ELEMENT (IANA SD-ID,
+ *  so no enterprise-number suffix), emitted on every message the owning logger
+ *  formats. It always carries sequenceId, taken from one Increment of the
+ *  injected AtomicCounter per message, and optionally sysUpTime and language.
+ *  The two optional PARAMs are independently omitted when their config member is
+ *  NULL, so a bare meta element is just [meta sequenceId="..."]. */
 #ifndef SOLIDSYSLOGMETASD_H
 #define SOLIDSYSLOGMETASD_H
 

Core/Interface/SolidSyslogMetaSdErrors.h

@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the MetaSd. */
 #ifndef SOLIDSYSLOGMETASDERRORS_H
 #define SOLIDSYSLOGMETASDERRORS_H
 

Core/Interface/SolidSyslogMutex.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The mutex role: mutual exclusion (Lock / Unlock) around buffer and pool
+ *  critical sections. These calls dispatch to the injected mutex's vtable, so
+ *  behaviour — including whether Lock blocks — is that mutex's. */
 #ifndef SOLIDSYSLOGMUTEX_H
 #define SOLIDSYSLOGMUTEX_H
 

Core/Interface/SolidSyslogMutexDefinition.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The Mutex vtable (Lock / Unlock) — the contract an implementor fills in (the
+ *  Mutex extension point). */
 #ifndef SOLIDSYSLOGMUTEXDEFINITION_H
 #define SOLIDSYSLOGMUTEXDEFINITION_H
 

Core/Interface/SolidSyslogNullAtomicCounter.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op AtomicCounter Null object: Increment returns 1U unconditionally, the safest
+ *  value when a real counter is unavailable (RFC 5424 §7.3.1 forbids a sequenceId of 0). */
 #ifndef SOLIDSYSLOGNULLATOMICCOUNTER_H
 #define SOLIDSYSLOGNULLATOMICCOUNTER_H
 

Core/Interface/SolidSyslogNullBlockDevice.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op BlockDevice Null object: every method reports a device that does not exist —
+ *  Acquire, Dispose, Exists, Read, Append and WriteAt return false, Size and GetBlockSize
+ *  return 0. */
 #ifndef SOLIDSYSLOGNULLBLOCKDEVICE_H
 #define SOLIDSYSLOGNULLBLOCKDEVICE_H
 

Core/Interface/SolidSyslogNullBuffer.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Buffer Null object: Write swallows the record, Read returns false (nothing to
+ *  deliver) so the Service algorithm sees an empty buffer and stops draining. */
 #ifndef SOLIDSYSLOGNULLBUFFER_H
 #define SOLIDSYSLOGNULLBUFFER_H
 

Core/Interface/SolidSyslogNullDatagram.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op Datagram Null object: SendTo returns SENT (drops the datagram on the floor so
+ *  the Store does not fill with undeliverables), MaxPayload returns the IPv6-safe default,
+ *  Open and Close are no-ops. */
 #ifndef SOLIDSYSLOGNULLDATAGRAM_H
 #define SOLIDSYSLOGNULLDATAGRAM_H
 

Core/Interface/SolidSyslogNullFile.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op File Null object: Open, IsOpen, Read and Exists return false (consumers take
+ *  their error path), Write and Delete return true (success reported vacuously), SeekTo,
+ *  Truncate and Close are no-ops, Size returns 0. */
 #ifndef SOLIDSYSLOGNULLFILE_H
 #define SOLIDSYSLOGNULLFILE_H
 

Core/Interface/SolidSyslogNullMutex.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Mutex Null object: Lock and Unlock are no-ops, giving unsynchronised access
+ *  for single-task targets that need no mutual exclusion. */
 #ifndef SOLIDSYSLOGNULLMUTEX_H
 #define SOLIDSYSLOGNULLMUTEX_H
 

Core/Interface/SolidSyslogNullResolver.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Resolver Null object: Resolve returns false (could not resolve) so the
+ *  caller's existing unresolved-host error path runs naturally. */
 #ifndef SOLIDSYSLOGNULLRESOLVER_H
 #define SOLIDSYSLOGNULLRESOLVER_H
 

Core/Interface/SolidSyslogNullSd.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Structured Data Null object: Format writes nothing, so this SD slot
+ *  contributes no SD-ELEMENT to the message. */
 #ifndef SOLIDSYSLOGNULLSD_H
 #define SOLIDSYSLOGNULLSD_H
 

Core/Interface/SolidSyslogNullSecurityPolicy.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op SecurityPolicy Null object: pass-through integrity — Seal and Open both return
+ *  true without touching the record, adding no integrity data and accepting every record. */
 #ifndef SOLIDSYSLOGNULLSECURITYPOLICY_H
 #define SOLIDSYSLOGNULLSECURITYPOLICY_H
 

Core/Interface/SolidSyslogNullSender.h

@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Sender Null object: Send returns true (drops the record on the floor so the
+ *  Store does not fill with undeliverables), Disconnect is a no-op. */
 #ifndef SOLIDSYSLOGNULLSENDER_H
 #define SOLIDSYSLOGNULLSENDER_H
 

Core/Interface/SolidSyslogNullStore.h

@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op Store Null object (no store-and-forward): Write returns false and IsTransient
+ *  returns true, so the Service algorithm falls through to a direct send instead of
+ *  buffering. ReadNextUnsent and HasUnsent report empty, IsHalted reports false. */
 #ifndef SOLIDSYSLOGNULLSTORE_H
 #define SOLIDSYSLOGNULLSTORE_H