docs: massive restructuring of documentation, development guides and agent playbooks

2026-06-15 12:54:38 +02:00
parent e4988b4397
commit ce63303b2c
686 changed files with 45423 additions and 319 deletions
@@ -0,0 +1,64 @@
+---
+type: Guide
+status: ACTIVE
+owner: Lead Architect
+tags: [coding-style, kdoc, documentation]
+last_update: 2026-03-15
+---
+
+# KDoc-Styleguide (Kurzfassung)
+
+Dieser Styleguide definiert die wichtigsten Regeln für KDoc-Kommentare in Kotlin-Projekten der Meldestelle. Ziel:
+Verständliche, konsistente API-Dokumentation via Dokka (GFM/HTML).
+
+## Grundregeln
+
+- Sprache: Deutsch für Fließtexte; Code/Bezeichner bleiben Englisch.
+- Jeder public class, interface, object, enum, public function und public property erhält einen KDoc-Block.
+- KDoc beginnt mit einem vollständigen, aussagekräftigen Satz in der dritten Person.
+- Beispiele und wichtige Hinweise als kurze Absätze oder Listen, keine Romane.
+
+## Struktur eines KDoc-Blocks
+
+```kotlin
+/**
+ * Beschreibt prägnant, was das Element macht und warum es existiert.
+ *
+ * Details: Optionale Erläuterung von Parametern, Nebenwirkungen, Fehlerfällen.
+ *
+ * @param id Eindeutige Kennung des Members
+ * @return Das gefundene Objekt oder null, wenn nicht vorhanden
+ * @throws IllegalArgumentException Falls Parameter ungültig sind
+ */
+fun findMember(id: MemberId): Member?
+```
+
+## Tags
+
+- @param: Für jeden Parameter bei public Funktionen
+- @return: Wenn Rückgabewert semantisch relevant ist
+- @throws: Relevante Exceptions dokumentieren
+- @since, @see: Sparsam verwenden, wenn es wirklichen Mehrwert bringt
+
+## Stil & Sprache
+
+- Klar, knapp, aktiv. Keine Redundanz.
+- Domänenbegriffe verwenden (BCs: members, horses, events, masterdata, infrastructure).
+- Keine Interna oder Secrets dokumentieren.
+
+## Beispielschnipsel
+
+```kotlin
+/** Erstellt einen neuen Event und persistiert ihn transaktional. */
+fun createEvent(cmd: CreateEventCommand): EventId
+```
+
+## Dokka-Hinweise
+
+- Dokka erzeugt GFM (Markdown) unter build/dokka/gfm und HTML unter build/dokka/html.
+- Source-Link führt auf GitHub (main-Branch). Prüfe Links in der CI.
+
+## Review
+
+- PR-Checklist: "KDoc vollständig?" anhaken, wenn neue public APIs hinzugekommen sind.
+- Vale/markdownlint gelten nur für .md; KDoc wird redaktionell in Code-Reviews geprüft.