breakpilot-pwa/docs-src/development/documentation.md

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:

• Aktualisiere die Backend API Dokumentation
• Aktualisiere Service-spezifische API-Docs

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:

• Aktualisiere die entsprechende README
• Fuege zur Umgebungs-Setup hinzu

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:

  === "Python"
      ```python
      print("Hello")
      ```
  
  === "Go"
      ```go
      fmt.Println("Hello")
      ```
  

• Mermaid-Diagramme fuer Visualisierungen:

  ```mermaid
  graph LR
      A --> B --> C