Skip to content

docs: godoc and package-doc pass#161

Merged
devarismeroxa merged 1 commit into
mainfrom
docs/godoc-pass
Jul 6, 2026
Merged

docs: godoc and package-doc pass#161
devarismeroxa merged 1 commit into
mainfrom
docs/godoc-pass

Conversation

@devarismeroxa

Copy link
Copy Markdown
Contributor

Summary

Docs-only pass on the processor SDK. No behavior, signature, or logic changes.

New doc.go files (2):

  • doc.go — root sdk package. Covers purpose, how to implement a Processor (embed UnimplementedProcessor), the method lifecycle and ordering, the ProcessedRecord return/error-propagation contract, the standalone (WASM) vs built-in hosting model, the schema encode/decode middleware, and neighboring packages.
  • schema/doc.goschema package. Covers Get/Create, how SchemaService differs between standalone (host registry) and built-in/test (in-memory) hosting, and caching.

Godoc added/improved on exported symbols (~9):

  • ErrFilterRecord — sentinel semantics (filter vs. fail) for NewProcessorFunc functions.
  • ProcessorFunc.Process — documents the truncate-on-first-error behavior (returned slice is shorter than input; remaining records are left for reprocessing), which is non-obvious from the signature.
  • schema: Get, Create, TypeAvro, SchemaService, ErrSubjectNotFound, ErrVersionNotFound, ErrInvalidSchema, InMemoryService, NewInMemoryService.

Highest-value contracts documented

  • Process lifecycle & ordering: Specification → Configure → Open → Process (repeated) → Teardown, called sequentially by the standalone command loop; idempotency requirement on Process.
  • Error propagation: how each ProcessedRecord type (SingleRecord / MultiRecord / FilterRecord / ErrorRecord) routes a record — continue / split / ack-and-drop / nack-to-DLQ — and that dropping an unprocessable record instead of returning ErrorRecord violates at-least-once.
  • WASM constraints: standalone processors compile to GOOS=wasip1 GOARCH=wasm and call Run as their entry point; built-in processors are invoked directly and skip the WebAssembly boundary; author code is identical in both modes.

Deliberately not documented

Skipped one-liner getters like SchemaPayloadEnabledParameterName / SchemaKeyEnabledParameterName and the wasm/pprocutils internal plumbing (their package docs already say "DO NOT use directly") — adding comments there would restate the name without adding information, against the "say something the signature doesn't" bar.

Verification

  • go build ./... — clean
  • go test ./... -count=1 — pass
  • GOOS=wasip1 GOARCH=wasm go build ./... — clean
  • make lint (golangci-lint v2.12.2) — 0 issues (baseline was also 0)

Risk tier: Tier 3 (docs/comments only). No data-path or contract change.

Add root and schema package doc.go files and document the highest-value
author-facing contracts: the Processor lifecycle, ProcessedRecord error
propagation semantics, and the standalone (WASM) vs built-in hosting model.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@devarismeroxa devarismeroxa requested a review from a team as a code owner July 6, 2026 01:01
@devarismeroxa devarismeroxa merged commit 5f48de3 into main Jul 6, 2026
3 checks passed
@devarismeroxa devarismeroxa deleted the docs/godoc-pass branch July 6, 2026 01:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant