Merge pull request #167 from data-altinn-no/feat/xml-descriptions

Add xml descriptions and update dataset alias

Dan.Common/Compat/AuthorizationRequirementJsonConverter.cs

@@ -11,11 +11,18 @@ namespace Dan.Common.Compat;
 /// </summary>
 public class AuthorizationRequirementJsonConverter : System.Text.Json.Serialization.JsonConverter<Requirement>
 {
+    /// <summary>
+    /// Not implemented
+    /// </summary>
+    /// <exception cref="NotImplementedException"></exception>
     public override Requirement Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Standard jsonconverter write implementation
+    /// </summary>
     public override void Write(Utf8JsonWriter writer, Requirement value, JsonSerializerOptions options)
     {
         writer.WriteStartObject();

Dan.Common/Constants.cs

@@ -1,5 +1,6 @@
 namespace Dan.Common;
 
+#pragma warning disable 1591
 /// <summary>
 /// Shared constants in Dan
 /// </summary>
@@ -81,3 +82,4 @@ public static class TextMacros
     public const string ConsentAndExternalReference = "#ConsentAndExternalReference#";
 
 }
+#pragma warning restore 1591

Dan.Common/Dan.Common.csproj

@@ -25,7 +25,8 @@
     <Authors>Altinn</Authors>
     <PackageProjectUrl>https://data.altinn.no</PackageProjectUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-    <Copyright>Copyright (c) Digitaliseringsdirektoratet 2022</Copyright>
+    <Copyright>Copyright (c) Digitaliseringsdirektoratet 2025</Copyright>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>

Dan.Common/Enums/FailureAction.cs

@@ -1,5 +1,8 @@
 namespace Dan.Common.Enums;
 
+/// <summary>
+/// Enum for determining what action to take if auth request is not satisfied
+/// </summary>
 public enum FailureAction
 {
     /// <summary>

Dan.Common/Enums/LogAction.cs

@@ -1,38 +1,63 @@
 namespace Dan.Common.Enums;
 
+/// <summary>
+/// Log action enum
+/// </summary>
 public enum LogAction
 {
-    // Used once per accreditation
+    /// <summary>
+    /// Used once per accreditation
+    /// </summary>
     AuthorizationGranted = 1,
 
-    // Used per consent request (one accreditation may incur several consent requests, each of which may span
-    // several datasets
+    /// <summary>
+    /// Used per consent request (one accreditation may incur several consent requests, each of which may span
+    /// several datasets
+    /// </summary>
     ConsentRequested = 2,
 
-    // As with ConsentRequested
+    /// <summary>
+    /// As with ConsentRequested
+    /// </summary>
     ConsentGiven = 3,
 
-    // As with ConsentRequested
+    /// <summary>
+    /// As with ConsentRequested
+    /// </summary>
     ConsentDenied = 4,
 
-    // Used for each harvest performed, of which there may be several per accreditation
+    /// <summary>
+    /// Used for each harvest performed, of which there may be several per accreditation
+    /// </summary>
     DatasetRetrieved = 5,
 
-    // As with ConsentRequested
+    /// <summary>
+    /// As with ConsentRequested
+    /// </summary>
     ConsentReminderSent = 6,
 
-    // Used when a open data set harvest is performed
+    /// <summary>
+    /// Used when a open data set harvest is performed
+    /// </summary>
     OpenDatasetRetrieved = 7,
 
-    // Used once per accreditation
+    /// <summary>
+    /// Used once per accreditation
+    /// </summary>
     AccreditationDeleted = 8,
 
-    // Used per data set requested for each AuthorizationGranted
+    /// <summary>
+    /// Used per data set requested for each AuthorizationGranted
+    /// </summary>
     DatasetRequested = 9,
 
-    // Used for each dataset in a consent request
+    /// <summary>
+    /// Used for each dataset in a consent request
+    /// </summary>
     DatasetRequiringConsentRequested = 10,
 
-    // Used for each correspondence sent related to consent requests (may be skipped, so counted seperately)
+    /// <summary>
+    /// Used for each correspondence sent related to consent requests (may be skipped, so counted seperately)
+    /// </summary>
     CorrespondenceSent = 11,
 }

Dan.Common/Extensions/HostBuilderExtensions.cs

@@ -13,6 +13,9 @@
 
 namespace Dan.Common.Extensions;
 
+/// <summary>
+/// HostBuilder extensions for setting up Dan plugin default configurations
+/// </summary>
 public static class HostBuilderExtensions
 {
     /// <summary>

Dan.Common/Interfaces/IEntityRegistryApiClientService.cs

@@ -1,11 +1,12 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
+namespace Dan.Common.Interfaces;
 
-namespace Dan.Common.Interfaces;
+/// <summary>
+/// API Service for fetching entity registries
+/// </summary>
 public interface IEntityRegistryApiClientService
 {
+    /// <summary>
+    /// Get entity registry unit
+    /// </summary>
     public Task<EntityRegistryUnit?> GetUpstreamEntityRegistryUnitAsync(Uri registryApiUri);
 }

Dan.Common/Interfaces/IEntityRegistryService.cs

@@ -1,4 +1,8 @@
 namespace Dan.Common.Interfaces;
+
+/// <summary>
+/// Service for handling entity registry
+/// </summary>
 public interface IEntityRegistryService
 {
     /// <summary>

Dan.Common/Interfaces/IServiceContextTextTemplate.cs

@@ -5,28 +5,64 @@
 /// </summary>
 public interface IServiceContextTextTemplate<out T>
 {
+    /// <summary>
+    /// Localised texts for consent request message
+    /// </summary>
     public LocalizedString ConsentDelegationContexts { get; }
 
+    /// <summary>
+    /// Email notification subject line
+    /// </summary>
     public T EmailNotificationSubject { get; }
 
+    /// <summary>
+    /// Email notification content
+    /// </summary>
     public T EmailNotificationContent { get; }
 
+    /// <summary>
+    /// SMS notification content
+    /// </summary>
     // ReSharper disable once InconsistentNaming
     public T SMSNotificationContent { get; }
 
+    /// <summary>
+    /// Correspondence sender name
+    /// </summary>
     public T CorrespondenceSender { get; }
 
+    /// <summary>
+    /// Correspondence title
+    /// </summary>
     public T CorrespondenceTitle { get; }
 
+    /// <summary>
+    /// Correspondence summary
+    /// </summary>
     public T CorrespondenceSummary { get; }
 
+    /// <summary>
+    /// Correspondence body
+    /// </summary>
     public T CorrespondenceBody { get; }
 
+    /// <summary>
+    /// Button text for giving consent
+    /// </summary>
     public T ConsentButtonText { get; }
 
+    /// <summary>
+    /// Receipt when giving consent
+    /// </summary>
     public T ConsentGivenReceiptText { get; }
 
+    /// <summary>
+    /// Receipt when denying consent
+    /// </summary>
     public T ConsentDeniedReceiptText { get; }
 
+    /// <summary>
+    /// Consent title text
+    /// </summary>
     public T ConsentTitleText { get; }
 }

Dan.Common/Models/Accreditation.cs

@@ -47,6 +47,9 @@ public class Accreditation
     [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
     public EvidenceStatusCode AggregateStatus { get; set; } = EvidenceStatusCode.Unknown;
 
+    /// <summary>
+    /// Flag to show if the accreditation is made from a direct harvest request
+    /// </summary>
     [DataMember(Name = "isDirectHarvest")]
     public bool IsDirectHarvest { get; set; }
 

Dan.Common/Models/AccreditationPartyRequirement.cs

@@ -14,6 +14,9 @@ public class AccreditationPartyRequirement : Requirement
     [JsonProperty(ItemConverterType = typeof(StringEnumConverter))]
     public List<AccreditationPartyRequirementType> PartyRequirements { get; set; }
 
+    /// <summary>
+    /// Default constructor, sets PartyRequirements to a new empty list
+    /// </summary>
     public AccreditationPartyRequirement()
     {
         PartyRequirements = new List<AccreditationPartyRequirementType>();

Dan.Common/Models/AuthorizationRequest.cs

@@ -60,12 +60,21 @@ public class AuthorizationRequest
     [DataMember(Name = "externalReference")]
     public string? ExternalReference { get; set; }
 
+    /// <summary>
+    /// Language code for the authorization request
+    /// </summary>
     [DataMember(Name = "languageCode")]
     public string? LanguageCode { get; set; }
 
+    /// <summary>
+    /// Redirect url for the consent receipt
+    /// </summary>
     [DataMember(Name = "consentReceiptRedirectUrl")]
     public string? ConsentReceiptRedirectUrl { get; set; }
 
+    /// <summary>
+    /// Flag to skip sending notification in Altinn
+    /// </summary>
     [DataMember(Name = "skipAltinnNotification")]
     public bool SkipAltinnNotification { get; set; }
 

Dan.Common/Models/DataRetrieval.cs

@@ -1,11 +1,20 @@
 namespace Dan.Common.Models;
 
+/// <summary>
+/// For determining what dataset had data retrieved from and when
+/// </summary>
 [DataContract]
 public class DataRetrieval
 {
+    /// <summary>
+    /// Name of dataset that data was retrieved from
+    /// </summary>
     [DataMember(Name = "evidenceCodeName")]
     public string? EvidenceCodeName { get; set; }
 
+    /// <summary>
+    /// When data was retrieved from dataset
+    /// </summary>
     [DataMember(Name = "timeStamp")]
     public DateTime TimeStamp { get; set; }
 }

Dan.Common/Models/DatasetAlias.cs

@@ -0,0 +1,17 @@
+namespace Dan.Common.Models;
+
+/// <summary>
+/// Model for alias for a dataset
+/// </summary>
+public class DatasetAlias
+{
+    /// <summary>
+    /// Which service context this alias applies to
+    /// </summary>
+    public string ServiceContext { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Alias name
+    /// </summary>
+    public string DatasetAliasName { get; set; } = string.Empty;
+}

Dan.Common/Models/EntityRegistryUnit.cs

@@ -2,6 +2,8 @@
 
 namespace Dan.Common.Models;
 
+// Not our model, can add descriptions to fields on request
+#pragma warning disable 1591
 // ReSharper disable once InconsistentNaming
 public class EntityRegistryUnit
 {
@@ -164,4 +166,5 @@ public class Organisasjonsform
 
     [JsonProperty("_links", Required = Required.Always)]
     public Links Links { get; set; } = null!;
-}
+}
+#pragma warning restore 1591

Dan.Common/Models/EvidenceCode.cs

@@ -147,10 +147,10 @@ public class EvidenceCode
     public string? License { get; set; }
 
     /// <summary>
-    /// Optional setting for aliases. Key is service context, value is Dataset name
+    /// Optional setting for aliases
     /// Allows for the same dataset to be shared between service contexts with different names.
     /// </summary>
     [DataMember(Name = "datasetAliases")]
     [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
-    public Dictionary<string,string>? DatasetAliases { get; set; }
+    public List<DatasetAlias>? DatasetAliases { get; set; }
 }

Dan.Common/Models/EvidenceHarvesterOptions.cs

@@ -1,5 +1,8 @@
 namespace Dan.Common.Models;
 
+/// <summary>
+/// Settings for handing access tokens for evidence harvesting
+/// </summary>
 public class EvidenceHarvesterOptions
 {
     /// <summary>

Dan.Common/Models/EvidenceStatusCode.cs

@@ -67,22 +67,24 @@ public class EvidenceStatusCode : IEquatable<EvidenceStatusCode>
     [DataMember(Name = "retryAt")]
     [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
     public DateTime? RetryAt { get; set; }
-
+
+    // Some default methods on method, shoud be self describing without descriptions what they do
+#pragma warning disable 1591    
     public bool Equals(EvidenceStatusCode? other)
     {
         if (ReferenceEquals(null, other)) return false;
         if (ReferenceEquals(this, other)) return true;
         return Code == other.Code;
     }
-
+    
     public override bool Equals(object? obj)
     {
         if (ReferenceEquals(null, obj)) return false;
         if (ReferenceEquals(this, obj)) return true;
         if (obj.GetType() != GetType()) return false;
         return Equals((EvidenceStatusCode)obj);
     }
-
+    
     public override int GetHashCode()
     {
         return Code.GetHashCode();
@@ -97,4 +99,5 @@ public override int GetHashCode()
     {
         return !Equals(left, right);
     }
+#pragma warning restore 1591
 }