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

* docs(public-api): DIN-orientierte XML-Dokumentation und Stil vereinheitlichen

* chore(ci): preflight nach PR-body-update neu auslösen

* chore(ci): whitespace-format für preflight korrigieren

* chore(style): reviewer-fixes und lesbarkeitsanpassungen

* docs(filetypedetector): dokumentation und signatur-layout nachziehen

---------

Co-authored-by: GitHub Copilot Agent <github-actions[bot]@users.noreply.github.com>

Author: tomtastisch

src/FileTypeDetection/Abstractions/Archive/ZipExtractedEntry.vb

@@ -6,11 +6,26 @@ Imports System.IO
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Unveraenderliches In-Memory-Ergebnis einer sicheren ZIP-Extraktion.
+    '''     Unveränderliches In-Memory-Modell eines sicher extrahierten Archiveintrags.
     ''' </summary>
+    ''' <remarks>
+    '''     Das Modell kapselt den normalisierten relativen Pfad und den unveränderlichen Byteinhalt eines Eintrags.
+    '''     Es ist für externe Konsumenten als read-only Datenträger vorgesehen.
+    ''' </remarks>
     Public NotInheritable Class ZipExtractedEntry
+        ''' <summary>
+        '''     Normalisierter relativer Eintragspfad innerhalb des Archivs.
+        ''' </summary>
         Public ReadOnly Property RelativePath As String
+
+        ''' <summary>
+        '''     Unveränderlicher Byteinhalt des Eintrags.
+        ''' </summary>
         Public ReadOnly Property Content As ImmutableArray(Of Byte)
+
+        ''' <summary>
+        '''     Größe des Eintragsinhalts in Bytes.
+        ''' </summary>
         Public ReadOnly Property Size As Integer
 
         Friend Sub New(entryPath As String, payload As Byte())
@@ -24,6 +39,13 @@ Namespace Global.Tomtastisch.FileClassifier
             End If
         End Sub
 
+        ''' <summary>
+        '''     Öffnet einen schreibgeschützten Speicherstream auf den Entry-Inhalt.
+        ''' </summary>
+        ''' <remarks>
+        '''     Der zurückgegebene Stream basiert auf einer isolierten Bytekopie und kann vom Aufrufer sicher gelesen werden.
+        ''' </remarks>
+        ''' <returns>Schreibgeschützter <see cref="MemoryStream"/> mit dem Entry-Inhalt.</returns>
         Public Function OpenReadOnlyStream() As MemoryStream
             Dim data = If(Content.IsDefaultOrEmpty, Array.Empty(Of Byte)(), Content.ToArray())
             Return New MemoryStream(data, writable:=False)

src/FileTypeDetection/Abstractions/Detection/DetectionDetail.vb

@@ -3,13 +3,36 @@ Option Explicit On
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Detailliertes, auditierbares Ergebnis einer Detektion.
+    '''     Detailliertes, auditierbares Ergebnis einer Detektionsentscheidung.
     ''' </summary>
+    ''' <remarks>
+    '''     Das Objekt transportiert den erkannten Typ sowie Trace-Merkmale, die für Compliance-, Diagnose- und
+    '''     Policy-Auswertungen vorgesehen sind.
+    ''' </remarks>
     Public NotInheritable Class DetectionDetail
+        ''' <summary>
+        '''     Finaler, nach allen Policies ermittelter Dateityp.
+        ''' </summary>
         Public ReadOnly Property DetectedType As FileType
+
+        ''' <summary>
+        '''     Deterministischer Grundcode für den eingeschlagenen Entscheidungs- oder Fehlerpfad.
+        ''' </summary>
         Public ReadOnly Property ReasonCode As String
+
+        ''' <summary>
+        '''     Kennzeichnet, ob eine inhaltsbasierte Archivprüfung durchgeführt wurde.
+        ''' </summary>
         Public ReadOnly Property UsedZipContentCheck As Boolean
+
+        ''' <summary>
+        '''     Kennzeichnet, ob ein strukturiertes Archiv-Refinement (z. B. OOXML) durchgeführt wurde.
+        ''' </summary>
         Public ReadOnly Property UsedStructuredRefinement As Boolean
+
+        ''' <summary>
+        '''     Kennzeichnet, ob die Endungs-Policy aktiv geprüft und bestätigt wurde.
+        ''' </summary>
         Public ReadOnly Property ExtensionVerified As Boolean
 
         Friend Sub New(

src/FileTypeDetection/Abstractions/Detection/FileKind.vb

@@ -4,23 +4,61 @@ Option Infer On
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Kanonische, in der Bibliothek unterstuetzte Dateitypen.
-    '''     Fachlicher Kontext:
-    '''     - DOCX/XLSX/PPTX sind fachlich ZIP-Container und werden erst nach ZIP-Gate verfeinert.
-    '''     - Archiv-Aliase wie tar/tgz/gz/bz2/xz/7z/rar/zz werden auf Kind Zip normalisiert.
+    '''     Kanonische, in der Bibliothek unterstützte Dateitypen.
     ''' </summary>
+    ''' <remarks>
+    '''     DOCX/XLSX/PPTX sind fachlich ZIP-Container und werden nach Archiv-Gate über strukturiertes Refinement
+    '''     verfeinert. Archiv-Aliase werden intern auf <see cref="Zip"/> normalisiert.
+    ''' </remarks>
     Public Enum FileKind
+        ''' <summary>
+        '''     Unbekannter oder nicht sicher klassifizierbarer Typ (fail-closed).
+        ''' </summary>
         Unknown = 0
 
+        ''' <summary>
+        '''     PDF-Dokument.
+        ''' </summary>
         Pdf
+
+        ''' <summary>
+        '''     PNG-Bilddatei.
+        ''' </summary>
         Png
+
+        ''' <summary>
+        '''     JPEG-Bilddatei.
+        ''' </summary>
         Jpeg
+
+        ''' <summary>
+        '''     GIF-Bilddatei.
+        ''' </summary>
         Gif
+
+        ''' <summary>
+        '''     WebP-Bilddatei.
+        ''' </summary>
         Webp
+
+        ''' <summary>
+        '''     ZIP-Container oder auf ZIP normalisierte Archivfamilie.
+        ''' </summary>
         Zip
 
+        ''' <summary>
+        '''     Office Open XML Word-Dokument (DOCX).
+        ''' </summary>
         Docx
+
+        ''' <summary>
+        '''     Office Open XML Excel-Dokument (XLSX).
+        ''' </summary>
         Xlsx
+
+        ''' <summary>
+        '''     Office Open XML PowerPoint-Dokument (PPTX).
+        ''' </summary>
         Pptx
     End Enum
 End Namespace

src/FileTypeDetection/Abstractions/Detection/FileType.vb

@@ -5,13 +5,18 @@ Imports System.Collections.Immutable
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Unveränderliches Wertobjekt für einen Dateityp.
-    '''     SSOT-Regel:
-    '''     - Instanzen werden zentral in FileTypeRegistry aufgebaut.
-    '''     - Aufrufer sollen keine ad-hoc FileType-Objekte erstellen.
+    '''     Unveränderliches Wertobjekt, das einen aufgelösten Dateityp einschließlich Metadaten beschreibt.
     ''' </summary>
+    ''' <remarks>
+    '''     <para>
+    '''         SSOT-Regel: Instanzen werden zentral über <c>FileTypeRegistry</c> aufgebaut.
+    '''     </para>
+    '''     <para>
+    '''         Konsumenten erhalten ein stabiles, read-only API-Modell mit kanonischer Endung, MIME und Aliasmenge.
+    '''     </para>
+    ''' </remarks>
     Public NotInheritable Class FileType
-        ''' <summary>Enum-Schluessel des Typs.</summary>
+        ''' <summary>Enum-Schlüssel des Typs.</summary>
         Public ReadOnly Property Kind As FileKind
 
         ''' <summary>Kanonische Endung inklusive Punkt, bei Unknown leer.</summary>
@@ -26,7 +31,7 @@ Namespace Global.Tomtastisch.FileClassifier
         Public ReadOnly Property Allowed As Boolean
 
         ''' <summary>
-        '''     Normalisierte Alias-Liste (ohne fuehrenden Punkt, dedupliziert).
+        '''     Normalisierte Alias-Liste (ohne führenden Punkt, dedupliziert).
         ''' </summary>
         Public ReadOnly Property Aliases As ImmutableArray(Of String)
 
@@ -54,6 +59,10 @@ Namespace Global.Tomtastisch.FileClassifier
             End If
         End Sub
 
+        ''' <summary>
+        '''     Liefert die textuelle Repräsentation des Dateityps auf Basis des Enum-Schlüssels.
+        ''' </summary>
+        ''' <returns>String-Repräsentation des Feldes <see cref="Kind"/>.</returns>
         Public Overrides Function ToString() As String
             Return Kind.ToString()
         End Function

src/FileTypeDetection/Abstractions/Hashing/HashDigestSet.vb

@@ -3,16 +3,50 @@ Option Explicit On
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Deterministische Hash-Sammlung fuer einen Verarbeitungsschritt.
+    '''     Deterministische Digest-Sammlung für einen Verarbeitungsschritt.
     ''' </summary>
+    ''' <remarks>
+    '''     Enthält logische und physische Hashwerte (inklusive optionaler Fast- und HMAC-Digests) in normalisierter Form.
+    ''' </remarks>
     Public NotInheritable Class HashDigestSet
+        ''' <summary>
+        '''     Physischer SHA-256-Digest des Quellpayloads.
+        ''' </summary>
         Public ReadOnly Property PhysicalSha256 As String
+
+        ''' <summary>
+        '''     Logischer SHA-256-Digest der kanonischen Sicht.
+        ''' </summary>
         Public ReadOnly Property LogicalSha256 As String
+
+        ''' <summary>
+        '''     Optionaler schneller physischer XxHash3-Digest.
+        ''' </summary>
         Public ReadOnly Property FastPhysicalXxHash3 As String
+
+        ''' <summary>
+        '''     Optionaler schneller logischer XxHash3-Digest.
+        ''' </summary>
         Public ReadOnly Property FastLogicalXxHash3 As String
+
+        ''' <summary>
+        '''     Optionaler HMAC-SHA256-Digest für den physischen Payload.
+        ''' </summary>
         Public ReadOnly Property HmacPhysicalSha256 As String
+
+        ''' <summary>
+        '''     Optionaler HMAC-SHA256-Digest für den logischen Payload.
+        ''' </summary>
         Public ReadOnly Property HmacLogicalSha256 As String
+
+        ''' <summary>
+        '''     Kennzeichnet, ob ein physischer Hashwert vorliegt.
+        ''' </summary>
         Public ReadOnly Property HasPhysicalHash As Boolean
+
+        ''' <summary>
+        '''     Kennzeichnet, ob ein logischer Hashwert vorliegt.
+        ''' </summary>
         Public ReadOnly Property HasLogicalHash As Boolean
 
         Friend Sub New(

src/FileTypeDetection/Abstractions/Hashing/HashEvidence.vb

@@ -3,18 +3,61 @@ Option Explicit On
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Nachweisobjekt fuer einen deterministischen Hash-Schritt.
+    '''     Nachweisobjekt für einen deterministischen Hash-Schritt.
     ''' </summary>
+    ''' <remarks>
+    '''     Das Objekt kapselt Herkunft, Typkontext, optionale Payloadkopien, Digest-Satz sowie ergänzende Notes in
+    '''     unveränderlicher Form für externe Auswertung.
+    ''' </remarks>
     Public NotInheritable Class HashEvidence
+        ''' <summary>
+        '''     Herkunftskanal des Nachweises.
+        ''' </summary>
         Public ReadOnly Property SourceType As HashSourceType
+
+        ''' <summary>
+        '''     Fachliches Label der Eingabequelle.
+        ''' </summary>
         Public ReadOnly Property Label As String
+
+        ''' <summary>
+        '''     Ermittelter Dateitypkontext für den Nachweis.
+        ''' </summary>
         Public ReadOnly Property DetectedType As FileType
+
+        ''' <summary>
+        '''     Optionaler Beispiel-Entry bei archivbasierten Nachweisen.
+        ''' </summary>
         Public ReadOnly Property Entry As ZipExtractedEntry
+
+        ''' <summary>
+        '''     Optional mitgeführte komprimierte Bytes.
+        ''' </summary>
         Public ReadOnly Property CompressedBytes As Global.System.Collections.Immutable.ImmutableArray(Of Byte)
+
+        ''' <summary>
+        '''     Optional mitgeführte unkomprimierte bzw. logische Bytes.
+        ''' </summary>
         Public ReadOnly Property UncompressedBytes As Global.System.Collections.Immutable.ImmutableArray(Of Byte)
+
+        ''' <summary>
+        '''     Anzahl berücksichtigter Entries im Nachweis.
+        ''' </summary>
         Public ReadOnly Property EntryCount As Integer
+
+        ''' <summary>
+        '''     Gesamtgröße unkomprimierter Nutzdaten in Bytes.
+        ''' </summary>
         Public ReadOnly Property TotalUncompressedBytes As Long
+
+        ''' <summary>
+        '''     Deterministischer Digest-Satz des Nachweises.
+        ''' </summary>
         Public ReadOnly Property Digests As HashDigestSet
+
+        ''' <summary>
+        '''     Ergänzende Hinweise, z. B. zu Fehlern oder Sicherheitsaspekten.
+        ''' </summary>
         Public ReadOnly Property Notes As String
 
         Friend Sub New(

src/FileTypeDetection/Abstractions/Hashing/HashOptions.vb

@@ -3,28 +3,32 @@ Option Explicit On
 
 Namespace Global.Tomtastisch.FileClassifier
     ''' <summary>
-    '''     Steuerung fuer deterministic hashing APIs.
+    '''     Konfiguriert das Verhalten der öffentlichen deterministischen Hashing-APIs.
     ''' </summary>
+    ''' <remarks>
+    '''     Die Optionen steuern, welche Digest-Arten berechnet und welche Payloadkopien in Evidence-Objekten mitgeführt werden.
+    '''     Ungültige Dateinamen für Materialisierung werden intern auf einen sicheren Standardwert normalisiert.
+    ''' </remarks>
     Public NotInheritable Class HashOptions
         ''' <summary>
-        '''     Wenn True, werden komprimierte und unkomprimierte Bytes in Evidence als Kopie mitgefuehrt.
+        '''     Wenn True, werden komprimierte und unkomprimierte Bytes in Evidence als Kopie mitgeführt.
         ''' </summary>
         Public Property IncludePayloadCopies As Boolean = False
 
         ''' <summary>
-        '''     Wenn True, wird zusaetzlich ein schneller XxHash3-Digest berechnet.
+        '''     Wenn True, wird zusätzlich ein schneller XxHash3-Digest berechnet.
         ''' </summary>
         Public Property IncludeFastHash As Boolean = True
 
         ''' <summary>
-        '''     Wenn True, wird zusaetzlich ein optionaler HMAC-SHA256 Digest berechnet (keyed).
+        '''     Wenn True, wird zusätzlich ein optionaler HMAC-SHA256 Digest berechnet (keyed).
         '''     Der Key wird aus der Environment Variable 'FILECLASSIFIER_HMAC_KEY_B64' gelesen.
-        '''     Wenn der Key fehlt oder ungueltig ist, werden HMAC-Digests leer gelassen und Notes ergaenzt.
+        '''     Wenn der Key fehlt oder ungültig ist, werden HMAC-Digests leer gelassen und Notes ergänzt.
         ''' </summary>
         Public Property IncludeSecureHash As Boolean = False
 
         ''' <summary>
-        '''     Dateiname fuer den Materialisierungs-Schritt im RoundTrip-Report.
+        '''     Dateiname für den Materialisierungs-Schritt im RoundTrip-Report.
         ''' </summary>
         Public Property MaterializedFileName As String = "deterministic-roundtrip.bin"