docs: give every package a doc comment and enforce it

.golangci.yml

@@ -66,7 +66,6 @@ linters:
         - name: blank-imports
           disabled: true
         - name: package-comments
-          disabled: true
         - name: var-naming
         - name: exported
         - name: if-return
@@ -84,7 +83,6 @@ linters:
   exclusions:
     generated: lax
     presets:
-      - comments
       - common-false-positives
       - legacy
       - std-error-handling
@@ -230,6 +228,9 @@ linters:
           - paralleltest
           - tparallel
         path: e2e/.*_test\.go
+      - linters:
+          - revive
+        text: '^exported: '
     paths:
       - third_party$
       - builtin$

cli/doc.go

@@ -0,0 +1,7 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package cli wires the daemon together: it parses flags and the INI
+// configuration, discovers jobs from Docker container labels, reconciles the
+// scheduler when either source changes, and owns the process lifecycle.
+package cli

config/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package config validates and sanitizes values that reach the daemon from
+// untrusted sources, most importantly the shell commands attached to jobs.
+package config

core/doc.go

@@ -0,0 +1,8 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package core holds the scheduler and the job types it runs: ExecJob (in a
+// running container), RunJob (in a fresh container), RunServiceJob (as a Swarm
+// service) and LocalJob (on the host). Docker access goes through the port
+// interfaces in core/ports so the scheduler stays independent of the SDK.
+package core

doc.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Ofelia is a job scheduler for Docker hosts, and a replacement for cron in
+// container environments. Jobs are declared in an INI file, through labels on
+// the containers themselves, or at runtime through the web API, and run either
+// inside an existing container, in a fresh one, on the host, or as a Swarm
+// service.
+//
+// Run the daemon with:
+//
+//	ofelia daemon --config=/etc/ofelia.conf
+//
+// Job results can be captured and forwarded by middlewares (log files, e-mail,
+// Slack, generic webhooks), and the daemon optionally serves a web UI and REST
+// API for inspecting and managing jobs.
+//
+// See https://github.com/netresearch/ofelia for configuration reference and
+// deployment guides.
+package main

metrics/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package metrics exposes scheduler and job statistics in Prometheus format,
+// plus HTTP middleware that records request metrics for the web server.
+package metrics

middlewares/doc.go

@@ -0,0 +1,7 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package middlewares implements the hooks that run around a job execution and
+// report its outcome: writing logs and JSON reports to disk, sending e-mail,
+// and posting to Slack or a generic webhook endpoint.
+package middlewares

static/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package static embeds the compiled assets of the web interface so the daemon
+// ships as a single binary.
+package static

test/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package test provides helpers shared across the test suites, such as a logger
+// that captures records for assertions.
+package test

web/doc.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 Netresearch DTT GmbH
+// SPDX-License-Identifier: MIT
+
+// Package web serves the browser interface and the REST API used to inspect
+// jobs, trigger runs, and manage jobs created at runtime.
+package web