2.0 KiB
2.0 KiB
| type | status | owner | tags | last_update | |||
|---|---|---|---|---|---|---|---|
| Guide | ACTIVE | Lead Architect |
|
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
/**
* 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
/** 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.