docs: S23.10 add @file briefs to the Core/Interface headers#612
Merged
Conversation
…nd vtables @file component briefs (fill the Headers browser + page overview) added ahead of the existing S23.02 symbol docs, on the mechanical role/template headers: - *Errors.h (11): "Error codes and Source identity for <X>" (+ the top-level singleton SolidSyslogErrors). - *Categories.h (5): the portable reaction-axis category macros per role. - SolidSyslogNull*.h (12): the no-op Null object + its safe return contract. - *Definition.h (12): the role vtable contract (extension point) + its slots. Existing symbol docs untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Behaviour-rich @file overviews (verified against Core/Source) on the 12 concrete Core classes: Crc16 / Crc16Policy (unkeyed CRC-16 integrity — corruption, not tamper-evidence), PassthroughBuffer (inline Write so Log blocks), CircularBuffer (uint16 length-prefixed ring, no-split wrap, drop-newest, mutex-bracketed), BlockStore (durable store-and-forward, discard policy, threshold callback + PassthroughBuffer recursion gotcha), FileBlockDevice (one file per block), MetaSd / OriginSd / TimeQualitySd (the RFC 5424 SD elements they emit), SwitchingSender (selector + NullSender fallback), StreamSender (RFC 6587 octet framing over any Stream), UdpSender (one datagram/record, oversize UTF-8-boundary trim, delivery-failed/restored reporting). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…types @file briefs on the remaining Core/Interface headers: - Role dispatch interfaces (Buffer / Store / Sender / Datagram / Stream / Resolver / Mutex / AtomicCounter / File / BlockDevice / StructuredData) — the role, and that calls dispatch to the injected implementation's vtable. - Application API (SolidSyslog / Config / ConfigLock), value types (Timestamp, Prival, Endpoint, EndpointHost, HeaderField, Address, Transport, ServiceStatus, TimeQuality), callback typedefs, SD-authoring (SdElement / SdValue), error infra (Error / ErrorCategory), and the tunables. ExternC = the C-linkage guard macros. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (9)
WalkthroughAdded ChangesCore interface documentation and additions
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
☀️ Quality Summary 🚦 build-linux-gcc: 100% successful (✔️ 1522 passed) Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
Core/Interface/SolidSyslogStreamDefinition.h (1)
18-23: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAlign the public stream blocking contract.
Core/Interface/SolidSyslogStream.hsays blocking discipline belongs to the injected stream, whereas this contract mandates “non-blocking bounded behaviour”. Those statements conflict and may lead implementers to provide incompatible transports. Make one guarantee authoritative and mirror it in both headers.As per path instructions,
Core/Interface/**/*.his the public API boundary, so this contract must be unambiguous.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@Core/Interface/SolidSyslogStreamDefinition.h` around lines 18 - 23, Align the blocking-discipline wording in SolidSyslogStreamDefinition.h with the authoritative contract in SolidSyslogStream.h. Update the stream contract documentation so both public headers make the same guarantee about blocking behavior, removing the conflicting “non-blocking bounded behaviour” mandate while preserving the documented slot semantics and close-on-failure lifecycle.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@Core/Interface/SolidSyslogCrc16Policy.h`:
- Around line 7-8: Update the SolidSyslogCrc16Policy documentation to replace
“authenticates” when describing the unkeyed CRC with “checks” or equivalent
checksum/integrity wording, while preserving the explanation that it processes
the content as one span.
In `@Core/Interface/SolidSyslogErrors.h`:
- Around line 1-2: Update the file-level documentation for SolidSyslogErrors to
describe it as “Error codes and source identity for the SolidSyslog instance,”
removing the misleading “Singleton” wording while preserving the rest of the
description.
In `@Core/Interface/SolidSyslogPassthroughBuffer.h`:
- Around line 8-10: Rename the header guard macro in
SolidSyslogPassthroughBuffer.h from SOLIDSYSLOGPASSTHROUGHBUFFER_H to
SOLIDSYSLOG_PASSTHROUGH_BUFFER_H, updating both the `#ifndef` and matching `#define`
occurrences.
In `@Core/Interface/SolidSyslogResolver.h`:
- Around line 2-3: Update the documentation for SolidSyslogResolver_Resolve to
describe the resolved address as being used by the later Datagram or Stream
sender for transmission, replacing the reference to those components reading it.
Leave the surrounding resolver role and dispatch description unchanged.
In `@Core/Interface/SolidSyslogResolverCategories.h`:
- Around line 2-3: Update the documentation brief in
SolidSyslogResolverCategories.h to name the declared public macro
SOLIDSYSLOG_CAT_RESOLVER_RESOLVE_FAILED instead of _RESOLVER_RESOLVE_FAILED,
ensuring the Headers browser links to the real identifier.
In `@Core/Interface/SolidSyslogStore.h`:
- Around line 1-5: Qualify the no-loss statement in the file-level documentation
for the store role: state that records accepted by the injected store are
retained and replayed, rather than implying records are never lost during an
outage. Do not change the fallback send behavior in SolidSyslog.c or claim
lossless delivery for records rejected by Write.
---
Outside diff comments:
In `@Core/Interface/SolidSyslogStreamDefinition.h`:
- Around line 18-23: Align the blocking-discipline wording in
SolidSyslogStreamDefinition.h with the authoritative contract in
SolidSyslogStream.h. Update the stream contract documentation so both public
headers make the same guarantee about blocking behavior, removing the
conflicting “non-blocking bounded behaviour” mandate while preserving the
documented slot semantics and close-on-failure lifecycle.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f073992a-e597-4d14-8f27-da4629c47afe
📒 Files selected for processing (89)
Core/Interface/ExternC.hCore/Interface/SolidSyslog.hCore/Interface/SolidSyslogAddress.hCore/Interface/SolidSyslogAtomicCounter.hCore/Interface/SolidSyslogAtomicCounterDefinition.hCore/Interface/SolidSyslogBlockDevice.hCore/Interface/SolidSyslogBlockDeviceDefinition.hCore/Interface/SolidSyslogBlockStore.hCore/Interface/SolidSyslogBlockStoreErrors.hCore/Interface/SolidSyslogBuffer.hCore/Interface/SolidSyslogBufferCategories.hCore/Interface/SolidSyslogBufferDefinition.hCore/Interface/SolidSyslogCircularBuffer.hCore/Interface/SolidSyslogCircularBufferErrors.hCore/Interface/SolidSyslogConfig.hCore/Interface/SolidSyslogConfigLock.hCore/Interface/SolidSyslogCrc16.hCore/Interface/SolidSyslogCrc16Policy.hCore/Interface/SolidSyslogDatagram.hCore/Interface/SolidSyslogDatagramDefinition.hCore/Interface/SolidSyslogEndpoint.hCore/Interface/SolidSyslogEndpointHost.hCore/Interface/SolidSyslogError.hCore/Interface/SolidSyslogErrorCategory.hCore/Interface/SolidSyslogErrors.hCore/Interface/SolidSyslogFile.hCore/Interface/SolidSyslogFileBlockDevice.hCore/Interface/SolidSyslogFileBlockDeviceErrors.hCore/Interface/SolidSyslogFileDefinition.hCore/Interface/SolidSyslogHeaderField.hCore/Interface/SolidSyslogHeaderFieldFunction.hCore/Interface/SolidSyslogKeyFunction.hCore/Interface/SolidSyslogMetaSd.hCore/Interface/SolidSyslogMetaSdErrors.hCore/Interface/SolidSyslogMutex.hCore/Interface/SolidSyslogMutexDefinition.hCore/Interface/SolidSyslogNullAtomicCounter.hCore/Interface/SolidSyslogNullBlockDevice.hCore/Interface/SolidSyslogNullBuffer.hCore/Interface/SolidSyslogNullDatagram.hCore/Interface/SolidSyslogNullFile.hCore/Interface/SolidSyslogNullMutex.hCore/Interface/SolidSyslogNullResolver.hCore/Interface/SolidSyslogNullSd.hCore/Interface/SolidSyslogNullSecurityPolicy.hCore/Interface/SolidSyslogNullSender.hCore/Interface/SolidSyslogNullStore.hCore/Interface/SolidSyslogNullStream.hCore/Interface/SolidSyslogOriginSd.hCore/Interface/SolidSyslogOriginSdErrors.hCore/Interface/SolidSyslogPassthroughBuffer.hCore/Interface/SolidSyslogPassthroughBufferErrors.hCore/Interface/SolidSyslogPrival.hCore/Interface/SolidSyslogResolver.hCore/Interface/SolidSyslogResolverCategories.hCore/Interface/SolidSyslogResolverDefinition.hCore/Interface/SolidSyslogSdElement.hCore/Interface/SolidSyslogSdValue.hCore/Interface/SolidSyslogSdValueFunction.hCore/Interface/SolidSyslogSecurityPolicyCategories.hCore/Interface/SolidSyslogSecurityPolicyDefinition.hCore/Interface/SolidSyslogSender.hCore/Interface/SolidSyslogSenderCategories.hCore/Interface/SolidSyslogSenderDefinition.hCore/Interface/SolidSyslogServiceStatus.hCore/Interface/SolidSyslogSleep.hCore/Interface/SolidSyslogStore.hCore/Interface/SolidSyslogStoreDefinition.hCore/Interface/SolidSyslogStream.hCore/Interface/SolidSyslogStreamDefinition.hCore/Interface/SolidSyslogStreamSender.hCore/Interface/SolidSyslogStreamSenderErrors.hCore/Interface/SolidSyslogStructuredData.hCore/Interface/SolidSyslogStructuredDataDefinition.hCore/Interface/SolidSyslogSwitchingSender.hCore/Interface/SolidSyslogSwitchingSenderErrors.hCore/Interface/SolidSyslogTcpConnectTimeoutFunction.hCore/Interface/SolidSyslogTimeQuality.hCore/Interface/SolidSyslogTimeQualitySd.hCore/Interface/SolidSyslogTimeQualitySdErrors.hCore/Interface/SolidSyslogTimestamp.hCore/Interface/SolidSyslogTlsHandshakeTimeoutFunction.hCore/Interface/SolidSyslogTlsStreamCategories.hCore/Interface/SolidSyslogTransport.hCore/Interface/SolidSyslogTunables.hCore/Interface/SolidSyslogTunablesDefaults.hCore/Interface/SolidSyslogUdpPayload.hCore/Interface/SolidSyslogUdpSender.hCore/Interface/SolidSyslogUdpSenderErrors.h
- Crc16Policy: unkeyed CRC "authenticates" -> "checks" the content (it is not authentication; the file already says it is not tamper-evidence). - Store: narrow the no-loss claim to a strong-but-scoped one — "a send failure never drops a stored record; it stays for retry" — rather than the absolute "nothing is lost across a send outage". (A record is only dropped in the double fault where the store's own Write fails and the fallback direct send also fails; that is by design, no code change.) - Errors: drop "Singleton" (the instance is the singleton, not the codes). - Resolver: address is "to send to", not "to read" (the Datagram/Stream use it for transmission). - *Categories (all 5): name the real SOLIDSYSLOG_CAT_* macros instead of the leading-underscore abbreviations, so the Headers-browser brief points at a real identifier. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
☀️ Quality Summary 🚦 build-linux-gcc: 100% successful (✔️ 1522 passed) Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
/** @file */briefs to all 89Core/Interfaceheaders — the sameconvention S23.09 (#607) applied to the platform headers. The Core headers
already carried the S23.02 symbol-level doc-comments but no
@fileblock, so theyrendered blank in the Headers browser and had no component overview at the top of
their page. This fills that in; the existing symbol docs are untouched.
Closes #611.
Shape
@filebrief per header — component identity, which fills the Headersbrowser entry and the page's top "Detailed Description".
FileBlockDevice, StreamSender / UdpSender / SwitchingSender / PassthroughBuffer,
MetaSd / OriginSd / TimeQualitySd) get a fuller
@filedescribing thesignificant behaviour, verified against
Core/Source— consistent with theplatform pass.
*Definition.hvtables / Null objects /*Errors.h/*Categories.hget concise role briefs.Commits (3 slices, for review granularity — squashes on merge)
Definitions (40).
@files (12).tunables (37).
Verification
@file; no collisions.clang-format --dry-run --Werrorclean.mkdocs build --strictexit 0.🤖 Generated with Claude Code
Summary by CodeRabbit