docs(public-api): DIN-orientierte Public-API-Dokumentation vereinheitlichen

[tomtastisch]

Ziel & Scope

• DIN-/NORM-orientierte XML-Dokumentation und Style-Vereinheitlichung für FileMaterializer und alle extern erreichbaren Public-API-Typen in src/FileTypeDetection.
• Strict Mode: keine Logikänderung, keine Public-Signaturänderung, keine Behavior-Änderung, keine neuen Dependencies.
• Fremddrift in src/FileTypeDetection/Infrastructure/CoreInternals.vb wurde bewusst nicht verändert.

Umgesetzte Aufgaben (abhaken)

• FileMaterializer vollständig dokumentiert (summary, remarks, param, returns, exception, example).
• Semantische Blocktrennung im FileMaterializer nach vorgegebenem Schema (Guard/Path/secureExtract/Raw-Fallback).
• Public-API-Klassenkopfstruktur in allen betroffenen Public-Typen vereinheitlicht.
• XML-Dokumentationsstandard auf alle betroffenen Public-API-Typen ausgerollt.
• Public-Member-Signaturen in konsistentes Multiline-Layout gebracht.
• Vorhandene Try/Catch-Layouts konsistent auf Catch-Filter-Form vereinheitlicht (ohne neue Fehlerpfade).

Nachbesserungen aus Review (iterativ)

• PR-Governance-kompatible Abschnittsstruktur in der PR-Beschreibung ergänzt.
• Terminologie konsolidiert (Materialize, Persist, Path, Fail-Closed).
• Dokumentationstexte auf Deutsch mit Umlauten nachgeschärft.
• Public-API-Snapshot erneut verifiziert (kein Diff).

Security- und Merge-Gates

• Branch-Schema erfüllt: codex/docs/public-api-doku-style-rollout.
• PR-Titel-Schema erfüllt: docs(public-api): ....
• Sicherheitsrelevante Checks lokal ausgeführt (Vulnerability Scan + Policy Checks).
• Pflichtaussage: security/code-scanning/tools mit 0 offene Alerts ist Merge-Voraussetzung; Merge erfolgt nur bei grünem Gate-Status.

Evidence (auditierbar)

• dotnet build FileClassifier.sln -> pass, 0 Fehler, 0 Warnungen.
• dotnet test FileClassifier.sln -> pass, 413/413.
• dotnet test tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj --filter "FullyQualifiedName~PublicApiContractSnapshotTests" -> pass, 1/1.
• git diff -- tests/FileTypeDetectionLib.Tests/Contracts/public-api.snapshot.txt -> kein Diff.
• python3 tools/check-docs.py -> Doc check OK.
• python3 tools/check-doc-consistency.py -> Doc consistency check OK.
• python3 tools/check-doc-shell-compat.py -> Doc shell compatibility check OK.
• dotnet list FileClassifier.sln package --vulnerable --include-transitive -> keine anfälligen Pakete.
• bash tools/ci/check-versioning-svt.sh -> pass.
• bash tools/ci/check-naming-snt.sh -> pass.

DoD (mindestens 2 pro Punkt)

Punkt	DoD A	DoD B
FileMaterializer-Dokumentation + Schema	Vollständige XML-Doku inkl. example in src/FileTypeDetection/FileMaterializer.vb	Build/Test grün nach Änderung (dotnet build, dotnet test)
Schema-Rollout Public API	16 Public-Typdateien konsistent angepasst (Commit-Dateiliste)	Public-API-Snapshot unverändert (public-api.snapshot.txt ohne Diff)
No-Logic-Change / No-Signature-Change	PublicApiContractSnapshotTests erfolgreich	Keine Vulnerability-/Policy-Regression (dotnet list --vulnerable, check-versioning-svt, check-naming-snt)

[Copilot]

Pull request overview

Vereinheitlicht die DIN-/NORM-orientierte XML-Dokumentation und das Layout der externen Public-API in src/FileTypeDetection (inkl. Catch-Filter-Form), ohne beabsichtigte Logik- oder Signaturänderungen.

Changes:

• XML-Dokumentation (summary/remarks/param/returns/exception/example) und Terminologie für Public-API-Typen vereinheitlicht.
• Signatur- und Layout-Harmonisierung (multiline Signaturen, Blocktrennung).
• Catch-Blöcke auf Catch-Filter-Form umgestellt (ohne intendierte Verhaltensänderung).

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/FileTypeDetection/FileTypeOptions.vb	Public-API-Doku/Remarks ergänzt; Catch-Layout in Options-Parsing/Path-Load vereinheitlicht.
src/FileTypeDetection/FileTypeDetector.vb	Public-API-Doku ausgebaut, Signaturlayout harmonisiert, Catch-Filter eingeführt.
src/FileTypeDetection/FileMaterializer.vb	Umfassende Public-API-Doku inkl. Beispiele; Catch-Filter-Umstellung (inkl. einem regressiven Log-Bug).
src/FileTypeDetection/EvidenceHashing.vb	XML-Doku für Hash-/RoundTrip-Fassade ergänzt; Catch-Filter-Form in Cleanup/Key-Parsing.
src/FileTypeDetection/Configuration/FileTypeProjectOptions.vb	Doku/Remarks zur Sicherheits- und Normalisierungslogik geschärft.
src/FileTypeDetection/Configuration/FileTypeProjectBaseline.vb	Baseline-Doku/Remarks und Nebenwirkungsbeschreibung ergänzt.
src/FileTypeDetection/ArchiveProcessing.vb	Öffentliche Archiv-Fassade dokumentiert, Parameter/Returns/Exceptions ergänzt.
src/FileTypeDetection/Abstractions/Hashing/HashSourceType.vb	Enum-Werte mit XML-Docs (auditierbarer Ursprungskanal) ergänzt.
src/FileTypeDetection/Abstractions/Hashing/HashRoundTripReport.vb	Report-Properties detailliert dokumentiert.
src/FileTypeDetection/Abstractions/Hashing/HashOptions.vb	Options-Doku/Remarks ergänzt (Normalisierung MaterializedFileName).
src/FileTypeDetection/Abstractions/Hashing/HashEvidence.vb	Evidence-Properties dokumentiert (Herkunft, Payloadkopien, Digests, Notes).
src/FileTypeDetection/Abstractions/Hashing/HashDigestSet.vb	Digest-Set-Properties dokumentiert (physisch/logisch, optional fast/HMAC).
src/FileTypeDetection/Abstractions/Detection/FileType.vb	FileType-Doku/Remarks und ToString-Doku ergänzt.
src/FileTypeDetection/Abstractions/Detection/FileKind.vb	Enum-Werte und fachlicher Kontext dokumentiert.
src/FileTypeDetection/Abstractions/Detection/DetectionDetail.vb	Detailobjekt/Properties für auditierbare Entscheidung dokumentiert.
src/FileTypeDetection/Abstractions/Archive/ZipExtractedEntry.vb	Entry-Modell/Properties und Stream-API dokumentiert.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.