From 002f9d0ba6cf70bf03739ffa6fae7176396d6694 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 10 Jun 2026 20:28:41 +0000 Subject: [PATCH] Clean up documentation consistency --- docs/integrations/events.md | 6 +++--- docs/operations.md | 2 +- docs/policy/architecture.md | 10 +++++----- docs/troubleshooting.md | 4 ++-- internal/normalizers/common/finalize.go | 6 +++--- internal/normalizers/common/json.go | 8 ++++---- internal/normalizers/nws/alerts.go | 2 +- model/alert.go | 2 +- model/forecast.go | 2 +- 9 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/integrations/events.md b/docs/integrations/events.md index 3209296..4a08a6e 100644 --- a/docs/integrations/events.md +++ b/docs/integrations/events.md @@ -101,8 +101,8 @@ Payload type: `WeatherForecastRun`. | `locationId` | string | no | Provider location identifier. | | `locationName` | string | no | Human location name. | | `issuedAt` | timestamp | yes | When the forecast run was generated or issued. | -| `updatedAt` | timestamp | no | Later provider update time. | -| `product` | string | yes | `hourly`, `narrative`, or `daily`. | +| `updatedAt` | timestamp | no | Subsequent provider update time. | +| `product` | string | yes | Current emitted values are `hourly` and `narrative`. | | `latitude` | number | no | Degrees. | | `longitude` | number | no | Degrees. | | `elevationMeters` | number | no | Meters. | @@ -145,7 +145,7 @@ Payload type: `WeatherForecastDiscussion`. | `officeName` | string | no | Office name. | | `product` | string | yes | Current value is `afd`. | | `issuedAt` | timestamp | yes | Bulletin issue time. | -| `updatedAt` | timestamp | no | Later update time. | +| `updatedAt` | timestamp | no | Subsequent update time. | | `keyMessages` | array of strings | no | Extracted key messages. | | `shortTerm` | object | no | Short-term section. | | `longTerm` | object | no | Long-term section. | diff --git a/docs/operations.md b/docs/operations.md index 14a6017..301f18a 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -62,7 +62,7 @@ and before each interval tick. If no jitter is configured in code, feedkit uses `min(every/10, 30s)`, capped at half the interval. Poll failures are logged and do not stop the daemon. A failed poll emits no -events for that source until a later poll succeeds. +events for that source until a subsequent poll succeeds. ## Conditional HTTP Fetches diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 7209846..67edf3c 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,11 +2,11 @@ ## Purpose -This document defines `weatherfeeder`'s development architecture and invariants for maintainers and LLM coding agents. It describes how the implemented system is built and how future changes should preserve its boundaries. +This document defines `weatherfeeder`'s development architecture and invariants for maintainers and LLM coding agents. It describes how the implemented system is built and how subsequent changes should preserve its boundaries. This is an inward-facing policy document. User-facing wire contracts belong in -[`docs/integrations/events.md`](../integrations/events.md), and future work -belongs under [`docs/roadmap/`](../roadmap/). +[`docs/integrations/events.md`](../integrations/events.md), and roadmap items +belong under [`docs/roadmap/`](../roadmap/). ## Project Shape @@ -57,9 +57,9 @@ Tests and examples: - The sample `cmd/weatherfeeder/config.yml` is executable test input and is load-tested. - Tests should keep exercising package contracts directly rather than relying only on full-daemon execution. -## Modules or Stages +## Modules Or Processing Steps -The implemented processing stages are source polling, normalization, dedupe, and sink dispatch. +The implemented processing steps are source polling, normalization, dedupe, and sink dispatch. Source contract: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1b283ce..b80b807 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -28,8 +28,8 @@ Diagnostic: inspect the line and field in the error. Feedkit uses strict YAML field decoding for config struct fields. Safe fix: correct the YAML and compare the shape with -[configuration](config.md). Driver-specific `params` keys are validated later by -their source or sink constructors. +[configuration](config.md). Driver-specific `params` keys are validated by their +source or sink constructors. ## `config validation failed` diff --git a/internal/normalizers/common/finalize.go b/internal/normalizers/common/finalize.go index 5e3ffc9..0818988 100644 --- a/internal/normalizers/common/finalize.go +++ b/internal/normalizers/common/finalize.go @@ -9,12 +9,12 @@ import ( ) // Finalize builds the output event envelope by copying the input and applying the -// canonical schema/payload, plus (optionally) EffectiveAt. +// canonical schema/payload, plus an optional effective time. // // Important behavior: // - ID/Kind/Source/EmittedAt are preserved by copying the input event. -// - EffectiveAt is only overwritten when effectiveAt is non-zero. -// If effectiveAt is zero, any existing in.EffectiveAt is preserved. +// - EffectiveAt is only overwritten when the supplied effective time is non-zero. +// If the supplied time is zero, any existing in.EffectiveAt is preserved. // - Payload floats are rounded to a stable wire-friendly precision (see round.go). func Finalize(in event.Event, outSchema string, outPayload any, effectiveAt time.Time) (*event.Event, error) { // Enforce stable numeric presentation for weather payloads before delegating to feedkit's diff --git a/internal/normalizers/common/json.go b/internal/normalizers/common/json.go index 590283f..3455d44 100644 --- a/internal/normalizers/common/json.go +++ b/internal/normalizers/common/json.go @@ -15,7 +15,7 @@ import ( // - sources emit raw JSON payloads (typically json.RawMessage) // - normalizers decode into provider structs // -// Errors include a small amount of stage context ("extract payload", "decode raw payload"). +// Errors include a small amount of operation context ("extract payload", "decode raw payload"). // Callers typically wrap these with a provider/kind label. func DecodeJSONPayload[T any](in event.Event) (T, error) { return fknormalize.DecodeJSONPayload[T](in) @@ -24,15 +24,15 @@ func DecodeJSONPayload[T any](in event.Event) (T, error) { // NormalizeJSON is a convenience wrapper for the common JSON-normalizer pattern: // // 1. Decode raw JSON payload into provider struct T -// 2. Map T into canonical payload P (plus an EffectiveAt timestamp) -// 3. Finalize the event envelope (schema/payload/effectiveAt) + Validate +// 2. Map T into canonical payload P (plus an effective time) +// 3. Finalize the event envelope (schema/payload/effective time) + Validate // // label should be short and specific, e.g. "openweather observation". // outSchema should be the canonical schema constant. // build should contain ONLY provider/domain mapping logic. // // Error policy: -// - NormalizeJSON wraps ALL failures with consistent context: "