Zum Inhalt

Dokumentations-Regeln

Automatische Dokumentations-Aktualisierung

WICHTIG: Bei JEDER Code-Aenderung muss die entsprechende Dokumentation aktualisiert werden!

Wann Dokumentation aktualisieren?

API-Aenderungen

Wenn du einen Endpoint aenderst, hinzufuegst oder entfernst:

Neue Funktionen/Klassen

Wenn du neue Funktionen, Klassen oder Module erstellst:

  • Aktualisiere die entsprechende Service-Dokumentation
  • Fuege Code-Beispiele hinzu

Architektur-Aenderungen

Wenn du die Systemarchitektur aenderst:

  • Aktualisiere die System-Architektur
  • Aktualisiere Datenmodell-Dokumentation bei DB-Aenderungen

Neue Konfigurationsoptionen

Wenn du neue Umgebungsvariablen oder Konfigurationen hinzufuegst:

Dokumentations-Format

API-Endpoints dokumentieren

### METHOD /path/to/endpoint

Kurze Beschreibung.

**Request Body:**
```json
{
  "field": "value"
}

Response (200): 

{
  "result": "value"
}

Errors: - 400: Beschreibung - 401: Beschreibung 

### Funktionen dokumentieren

```markdown
### FunctionName (file.go:123)

```go
func FunctionName(param Type) ReturnType

Beschreibung: Was macht die Funktion?

Parameter: - param: Beschreibung

Rueckgabe: Beschreibung 

## Checkliste nach Code-Aenderungen

Vor dem Abschluss einer Aufgabe pruefen:

- [ ] Wurden neue API-Endpoints hinzugefuegt? → API-Docs aktualisieren
- [ ] Wurden Datenmodelle geaendert? → Architektur-Docs aktualisieren
- [ ] Wurden neue Konfigurationen hinzugefuegt? → README aktualisieren
- [ ] Wurden neue Abhaengigkeiten hinzugefuegt? → requirements.txt/go.mod UND Docs
- [ ] Wurde die Architektur geaendert? → architecture/ aktualisieren

## Beispiel: Vollstaendige Dokumentation einer neuen Funktion

Wenn du z.B. `GetUserStats()` im Go Service hinzufuegst:

1. **Code schreiben** in `internal/services/stats_service.go`
2. **API-Doc aktualisieren** in der API-Dokumentation
3. **Service-Doc aktualisieren** in der Service-README
4. **Test schreiben** (siehe [Testing](./testing.md))

## Dokumentations-Struktur

Die zentrale Dokumentation befindet sich unter `docs-src/`:
docs-src/ ├── index.md # Startseite ├── getting-started/ # Erste Schritte │ ├── environment-setup.md │ └── mac-mini-setup.md ├── architecture/ # Architektur-Dokumentation │ ├── system-architecture.md │ ├── auth-system.md │ └── ... ├── api/ # API-Dokumentation │ └── backend-api.md ├── services/ # Service-Dokumentation │ ├── klausur-service/ │ ├── agent-core/ │ └── ... ├── development/ # Entwickler-Guides │ ├── testing.md │ └── documentation.md └── guides/ # Weitere Anleitungen ```

MkDocs Konventionen

Diese Dokumentation wird mit MkDocs + Material Theme generiert:

  • Admonitions fuer Hinweise: ```markdown !!! note "Hinweis" Wichtige Information hier.

!!! warning "Warnung" Vorsicht bei dieser Aktion. ```

  • Code-Tabs fuer mehrere Sprachen: markdown === "Python"python print("Hello") ```

=== "Go" go fmt.Println("Hello") ```

  • Mermaid-Diagramme fuer Visualisierungen: markdownmermaid graph LR A --> B --> C