add XML documentation, closes #10

dopt.DeltaBarth/DataObjects.cs

@@ -7,44 +7,130 @@ using System.Collections.Immutable;
 
 namespace dopt.DeltaBarth.DataObjects
 {
+    /// <summary>
+    /// Eine verpackte Fehlermeldung, die vom API-Server zur Verfügung gestellt wurde.
+    /// </summary>
     public record class ApiServerError
     {
+        /// <summary>
+        /// Statuscode der HTTP-Anfrage
+        /// </summary>
         public required int status_code { get; init; }
+        /// <summary>
+        /// Fehlerbezeichnung
+        /// </summary>
         public required string message { get; init; }
+        /// <summary>
+        /// optional: spezifischer Code als Text, der vom Server ausgegeben wurde
+        /// </summary>
         public string? code { get; init; }
+        /// <summary>
+        /// optional: spezifische Hinweise als Text, der vom Server ausgegeben wurde
+        /// </summary>
         public string? hints { get; init; }
+        /// <summary>
+        /// optional: spezifischer Typus als Text, der vom Server ausgegeben wurde
+        /// </summary>
         public string? type { get; init; }
+        /// <summary>
+        /// optional: spezifischer Titel als Text, der vom Server ausgegeben wurde
+        /// </summary>
         public string? title { get; init; }
+        /// <summary>
+        /// optional: spezifischer ID (vermutlich zur Nachverfolgung) als Text, der vom Server ausgegeben wurde
+        /// </summary>
         public string? traceId { get; init; }
     }
+    /// <summary>
+    /// Status-Objekt: Gibt Aufschluss über Erfolg/Misserfolg einer Routine und beschreibt aufgetretene Fehler 
+    /// mit zusätzlichen Informationen
+    /// </summary>
     public record class Status
     {
+        /// <summary>
+        /// bibliotheksinterner Fehlercode
+        /// </summary>
         public required int code { get; init; }
+        /// <summary>
+        /// Fehlerbeschreibung oder Python-Exception-Name
+        /// </summary>
         public required string description { get; init; }
+        /// <summary>
+        /// genauere Beschreibung oder Fehler-Inhalt
+        /// </summary>
         public required string message { get; init; }
+        /// <summary cref="ApiServerError">
+        /// optional: eventuell aufgetretener API-Server-Fehler
+        /// </summary>
         public ApiServerError? apiServerError { get; init; }
 
     }
+    /// <summary>
+    /// Nutzerdaten zur API-Interaktion
+    /// </summary>
     public record class Credentials
     {
+        /// <summary>
+        /// Nutzername
+        /// </summary>
         public required string username { get; init; }
+        /// <summary>
+        /// Passwort
+        /// </summary>
         public required string password { get; init; }
+        /// <summary>
+        /// Datenbank
+        /// </summary>
         public required string database {  get; init; }
+        /// <summary>
+        /// Mandant
+        /// </summary>
         public required string mandant { get; init; }
     }
+    /// <summary>
+    /// Einzelergebnis der Umsatzprognose, 1 Eintrag von potenziell mehreren
+    /// </summary>
     public record class UmsatzPrognoseEinzelergebnis
     {
+        /// <summary>
+        /// Jahr des Eintrags
+        /// </summary>
         public required int jahr {  get; init; }
+        /// <summary>
+        /// Monat des Eintrags
+        /// </summary>
         public required int monat { get; init; }
+        /// <summary>
+        /// Prognosewert für den Umsatz
+        /// </summary>
         public required decimal vorhersage { get; init; }
     }
+    /// <summary>
+    /// Sammlung von unterschiedlichen Einzelergebnissen
+    /// <see cref="UmsatzPrognoseEinzelergebnis"/>
+    /// </summary>
     public record class UmsatzPrognoseErgebnisse
     {
+        /// <summary>
+        /// unveränderliche Sammlung von Einzelergebnissen in Form eines Array
+        /// </summary>
         public required ImmutableArray<UmsatzPrognoseEinzelergebnis> daten {  get; init; }
     }
+    /// <summary>
+    /// Ausgabe der Prognose-Pipeline:
+    /// enthält das Ergebnis als auch einen dazugehörigen Status
+    /// </summary>
     public record class UmsatzPrognoseAusgabe
     {
+        /// <summary>
+        /// Sammlung von Prognosewerten
+        /// <see cref="UmsatzPrognoseErgebnisse"/>
+        /// </summary>
         public required UmsatzPrognoseErgebnisse response { get; init; }
+        /// <summary>
+        /// Status über den Erfolg/Misserfolg der Routine
+        /// <see cref="Status"/>
+        /// </summary>
         public required Status status { get; init; }
     }
 }

dopt.DeltaBarth/Plugin.cs

@@ -4,32 +4,95 @@ using System.Text.Json;
 
 namespace dopt.DeltaBarth
 {
+    /// <summary>
+    /// Spiegelung der internen Fehlertypen innerhalb der Python-Bibliothek
+    /// </summary>
     public enum StatusCodes
     {
+        /// <summary>
+        /// erfolgreiche, fehlerfreie Durchführung der Routine
+        /// </summary>
         [Description("Keine Fehler aufgetreten")]
         Erfolg = 0,
+        /// <summary>
+        /// Bei der API-Abfrage wurde der Timeout getriggert.
+        /// </summary>
         [Description("Bei der Verbindung zum API-Server kam es zum Timeout")]
         VerbindungTimeout = 1,
+        /// <summary>
+        /// Bei der API-Abfrage ist ein unerwarteter Fehler aufgetreten, der unmittelbar die HTTP-Anfrage betrifft.
+        /// </summary>
         [Description("Bei der Verbindung zum API-Server ist ein Fehler aufgetreten")]
         VerbindungFehler = 2,
+        /// <summary>
+        /// Der ausgewählte Datensatz enthält nicht genügend Datenpunkte.
+        /// </summary>
         [Description("Der bereitgestellte Datensatz enthält in Summe zu wenige Einzeleinträge")]
         DatensatzZuWenigeDatenpunkte = 3,
+        /// <summary>
+        /// Der ausgewählte Datensatz enthält nach Aggregation pro Monat nicht genügend Datenpunkte.
+        /// </summary>
         [Description("Der bereitgestellte Datensatz enthält nach Aggregation zu Monaten zu wenig Einträge")]
         DatensatzZuWenigeMonatsdatenpunkte = 4,
-        [Description("Die Prognosequalität des Modells erfüllt nicht ide Mindestanforderungen")]
+        /// <summary>
+        /// Die Prognosequalität des Modells ist nicht zufriedenstellend. Eine verlässliche Prognose ist nicht möglich.
+        /// </summary>
+        [Description("Die Prognosequalität des Modells erfüllt nicht die Mindestanforderungen")]
         KeineVerlaesslichePrognose = 5,
+        /// <summary>
+        /// Es ist intern ein Fehler aufgetreten aufgetreten
+        /// </summary>
+        [Description("Interne Fehler, die während der Routine aufgetreten sind")]
+        InternerFehler = 100,
+        /// <summary>
+        /// Es ist ein Fehler beim Schreiben der programminternen Datenbank aufgetreten.
+        /// </summary>
+        [Description("Interne Fehler, die während der Datenbankinteraktion aufgetreten sind")]
+        InternerDbFehler = 150,
+        /// <summary>
+        /// Es ist ein Fehler auf dem API-Server aufgetreten. 
+        /// Das dazugehörige Status-Objekt sollte diesen Fehler zur Verfügung stellen können.
+        /// <see cref="DataObjects.Status"/>
+        /// <see cref="DataObjects.ApiServerError"/>
+        /// </summary>
         [Description("Vom API-Server wurde eine Fehlermeldung zurückgegeben")]
         ApiServerFehler = 400,
     }
+    /// <summary>
+    /// Eine Exception, die genutzt wird, um anzuzeigen, dass beim Parsen der Python-Objekte
+    /// ein Fehler aufgetreten ist.
+    /// </summary>
     public class PythonParsingException : Exception
     {
+        /// <summary>
+        /// Konstruktor ohne Inhalt
+        /// </summary>
         public PythonParsingException() { }
+        /// <summary>
+        /// Konstruktor mit Nachricht
+        /// </summary>
+        /// <param name="message"></param>
         public PythonParsingException(string message) : base(message) { }
     }
+    /// <summary>
+    /// Plugin-Klasse, mit der die Interaktion der zugrundeliegenden Python-Runtime erfolgt
+    /// </summary>
     public class Plugin : SharpPython.BasePlugin
     {
+        /// <summary>
+        /// Python-interne Zustandsverwaltung
+        /// </summary>
         protected dynamic pyModManagement;
+        /// <summary>
+        /// Python-interne Routinen und Pipelines
+        /// </summary>
         protected dynamic pyModPipeline;
+        /// <summary>
+        /// Konstruktor der Plugin-Klasse.
+        /// Kann mit beliebigem Pfad zu einer Python-Runtime initialisiert werden.
+        /// </summary>
+        /// <param name="runtimePath">Der Pfad zur Python-Runtime. Dieser muss zu dem Ordner zeigen, 
+        /// in welchem die Runtime in Form eines Ordners mit dem Namen "python" abliegt.</param>
         public Plugin(string runtimePath) : base(runtimePath: runtimePath, verbose: false) 
         {
             base.Initialise();
@@ -39,12 +102,30 @@ namespace dopt.DeltaBarth
                 pyModPipeline = Py.Import("delta_barth.pipelines");
             }
         }
+        /// <summary>
+        /// Initialisiert das Plugin mit allen relevanten Paramtern für die weitere Nutzung.
+        /// Diese Methode sollte nur einmal je Instanz genutzt werden.
+        /// </summary>
+        /// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
+        /// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
+        /// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
+        /// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
+        /// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
+        /// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
         public void Startup(string datenPfad, string basisApiUrl, string nutzername, string passwort, string datenbank, string mandant)
         {
             AssertNotDisposed();
             Setup(datenPfad, basisApiUrl);
             SetzeNutzerdaten(nutzername, passwort, datenbank, mandant);
         }
+        /// <summary>
+        /// Diese Methode erlaubt es, die relevanten Nutzerdaten zur Laufzeit des Plugins zu ändern.
+        /// Dies beinhaltet: Nutzername, Passwort, Datenbankname, Mandant
+        /// </summary>
+        /// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
+        /// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
+        /// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
+        /// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
         public void SetzeNutzerdaten(string nutzername, string passwort, string datenbank, string mandant)
         {
             AssertNotDisposed();
@@ -52,6 +133,17 @@ namespace dopt.DeltaBarth
                 pyModManagement.set_credentials(nutzername, passwort, datenbank, mandant);
             }
         }
+        /// <summary>
+        /// Ausführung der Umsatzprognose-Pipeline mit Dummy-Daten.
+        /// Es werden keine API-Abrufe durchgeführt und somit auch keine Live-Daten genutzt.
+        /// </summary>
+        /// <param name="firmaId">optional: Firmen-ID, für die die Pipeline ausgeführt werden soll. 
+        /// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
+        /// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
+        /// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt. 
+        /// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
+        /// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
+        /// <exception cref="PythonParsingException"></exception>
         public DataObjects.UmsatzPrognoseAusgabe UmsatzprognoseDummy(int? firmaId, DateTime? analyseBeginn)
         {
             AssertNotDisposed();
@@ -63,6 +155,18 @@ namespace dopt.DeltaBarth
             var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
             return parsed;
         }
+        /// <summary>
+        /// Ausführung der Umsatzprognose-Pipeline mit Live-Daten.
+        /// Es werden API-Abrufe durchgeführt und somit auch Live-Daten genutzt. 
+        /// Hierfür muss sichergestellt sein, dass der API-Server erreichbar und abrufbereit ist.
+        /// </summary>
+        /// <param name="firmaId">optional: Firmen-ID, für die die Pipeline ausgeführt werden soll. 
+        /// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
+        /// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
+        /// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt. 
+        /// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
+        /// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
+        /// <exception cref="PythonParsingException"></exception>
         public DataObjects.UmsatzPrognoseAusgabe Umsatzprognose(int? firmaId, DateTime? analyseBeginn)
         {
             AssertNotDisposed();
@@ -74,6 +178,11 @@ namespace dopt.DeltaBarth
             var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
             return parsed;
         }
+        /// <summary>
+        /// Setup der Python-internen Umgebung
+        /// </summary>
+        /// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
+        /// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
         protected void Setup(string datenPfad, string basisApiUrl)
         {
             AssertNotDisposed();
@@ -82,6 +191,10 @@ namespace dopt.DeltaBarth
                 pyModManagement.setup(datenPfad, basisApiUrl);
             }
         }
+        /// <summary>
+        /// Hole die konfigurierte API-Basis-URL aus der Python-Umgebung
+        /// </summary>
+        /// <returns>konfigurierte Basis-URL</returns>
         protected string GetBaseApiUrl()
         {
             AssertNotDisposed();
@@ -92,6 +205,10 @@ namespace dopt.DeltaBarth
             }
             return pyJson;
         }
+        /// <summary>
+        /// Hole den konfigurierten Datenpfad zur Dateiverwaltung aus der Python-Umgebung
+        /// </summary>
+        /// <returns>konfigurierten Datenpfad</returns>
         protected string GetDataPath()
         {
             AssertNotDisposed();
@@ -102,6 +219,11 @@ namespace dopt.DeltaBarth
             }
             return pyJson;
         }
+        /// <summary>
+        /// Hole die konfigurierten Nutzerdaten zur API-Interaktion aus der Python-Umgebung
+        /// </summary>
+        /// <returns cref="DataObjects.Credentials">konfigurierte Nutzerdaten</returns>
+        /// <exception cref="PythonParsingException"></exception>
         protected DataObjects.Credentials GetCredentials()
         {
             AssertNotDisposed();

dopt.DeltaBarth/dopt.DeltaBarth.csproj

@@ -7,6 +7,7 @@
     <PlatformTarget>x64</PlatformTarget>
     <Platforms>x64</Platforms>
     <Version>0.3.3-dev1</Version>
+    <GenerateDocumentationFile>True</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>