Add docs to generated public types and members.

Author: PawelGerr

Directory.Build.props

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <Copyright>(c) $([System.DateTime]::Now.Year), Pawel Gerr. All rights reserved.</Copyright>
-    <VersionPrefix>9.5.2</VersionPrefix>
+    <VersionPrefix>9.5.3</VersionPrefix>
     <Authors>Pawel Gerr</Authors>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageProjectUrl>https://github.com/PawelGerr/Thinktecture.Runtime.Extensions</PackageProjectUrl>

README.md

@@ -30,9 +30,11 @@ See [wiki](https://github.com/PawelGerr/Thinktecture.Runtime.Extensions/wiki) fo
 * [Value Objects: Solving Primitive Obsession in .NET](https://www.thinktecture.com/en/net/value-objects-solving-primitive-obsession-in-net/)
 * [Handling Complexity: Introducing Complex Value Objects in .NET](https://www.thinktecture.com/en/net/handling-complexity-introducing-complex-value-objects-in-dotnet/)
 * [Value Objects in .NET: Integration with Frameworks and Libraries](https://www.thinktecture.com/en/net/value-objects-integration-with-frameworks-and-libraries/)
+* [Value Objects in .NET: Enhancing Business Semantics](https://www.thinktecture.com/en/net/value-objects-in-dotnet-enhancing-business-semantics/)
 
 **Smart Enums articles**:
 * [Smart Enums: Beyond Traditional Enumerations in .NET](https://www.thinktecture.com/en/net/smart-enums-beyond-traditional-enumerations-in-dotnet/)
+* [Smart Enums: Adding Domain Logic to Enumerations in .NET](https://www.thinktecture.com/net/smart-enums-adding-domain-logic-to-enumerations-in-dotnet/)
 
 **Discriminated Unions articles**:
 * [Discriminated Unions: Representation of Alternative Types in .NET](https://www.thinktecture.com/net/discriminated-unions-representation-of-alternative-types-in-dotnet/)

docs

@@ -33,7 +33,7 @@ internal static class DiagnosticsDescriptors
    public static readonly DiagnosticDescriptor TypeMustNotBeInsideGenericType = new("TTRESG052", "The type must not be inside generic type", "Type '{0}' must not be inside a generic type", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor UnionDerivedTypesMustNotBeGeneric = new("TTRESG053", "Derived type of a union must not be generic", "Derived type '{0}' of a union must not be generic", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor UnionMustBeSealedOrHavePrivateConstructorsOnly = new("TTRESG054", "Discriminated union must be sealed or have private constructors only", "Discriminated union '{0}' must be sealed or have private constructors only", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
-   public static readonly DiagnosticDescriptor UnionRecordMustBeSealed = new("TTRESG055", "Discriminated union implemented using a record must be sealed", "Discriminated union '{0}' using a record must be sealed", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
+   public static readonly DiagnosticDescriptor UnionRecordMustBeSealed = new("TTRESG055", "Discriminated union implemented using a record must be sealed", "Discriminated union '{0}' using a record must be sealed. Use a class for nesting unions.", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor NonAbstractDerivedUnionIsLessAccessibleThanBaseUnion = new("TTRESG056", "Non-abstract derived union is less accessible than base union", "Non-abstract derived union '{0}' is less accessible than base union '{1}'", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor AllowDefaultStructsCannotBeTrueIfValueObjectIsStructButKeyTypeIsClass = new("TTRESG057", "'AllowDefaultStructs' must be 'false' if Value Object is a struct but key type is a reference type", "'AllowDefaultStructs' of type '{0}' must be 'false' because it is a struct but the key type '{1}' is a reference type", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor AllowDefaultStructsCannotBeTrueIfSomeMembersDisallowDefaultValues = new("TTRESG058", "'AllowDefaultStructs' must be 'false' if some members disallow default values", "'AllowDefaultStructs' of type '{0}' must be 'false' because following members disallow default values: {1}", nameof(ThinktectureRuntimeExtensionsAnalyzer), DiagnosticSeverity.Error, true);

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/DiagnosticsDescriptors.cs

@@ -119,6 +119,21 @@ private void GenerateCreateMethod()
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Creates an instance of the ").AppendTypeForXmlComment(_state).Append(@" type if the provided values pass validation.
+      /// </summary>");
+
+      for (var i = 0; i < fieldsAndProperties.Count; i++)
+      {
+         var memberInfo = fieldsAndProperties[i];
+
+         _sb.Append(@"
+      /// <param name=""").Append(memberInfo.ArgumentName).Append(@""">The value to be used for object creation.</param>");
+      }
+
+      _sb.Append(@"
+      /// <returns>A newly created ").AppendTypeForXmlComment(_state).Append(@" instance.</returns>
+      /// <exception cref=""System.ComponentModel.DataAnnotations.ValidationException"">Thrown when the provided values fail validation.</exception>
       public static ").AppendTypeFullyQualified(_state).Append(" ").Append(_state.Settings.CreateFactoryMethodName).Append("(").RenderArgumentsWithType(fieldsAndProperties, prefix: @"
          ", comma: ",").Append(@")
       {
@@ -146,6 +161,27 @@ private void GenerateTryCreateMethod()
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Attempts to create an instance of type ").AppendTypeForXmlComment(_state).Append(@"
+      /// if the provided values pass validation.
+      /// </summary>");
+
+      for (var i = 0; i < fieldsAndProperties.Count; i++)
+      {
+         var memberInfo = fieldsAndProperties[i];
+
+         _sb.Append(@"
+      /// <param name=""").Append(memberInfo.ArgumentName).Append(@""">The value to be used for object creation.</param>");
+      }
+
+      _sb.Append(@"
+      /// <param name=""obj"">
+      /// When this method returns, contains the created instance of type ").AppendTypeForXmlComment(_state).Append(@"
+      /// if the operation is successful; otherwise, <c>null</c>.
+      /// </param>
+      /// <returns>
+      /// <c>true</c> if the instance is successfully created; otherwise, <c>false</c>.
+      /// </returns>
       public static bool ").Append(_state.Settings.TryCreateFactoryMethodName).Append("(");
 
       _sb.RenderArgumentsWithType(fieldsAndProperties, @"
@@ -169,6 +205,31 @@ private void GenerateTryCreateMethod()
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Attempts to create an instance of type ").AppendTypeForXmlComment(_state).Append(@"
+      /// if the provided values pass validation.
+      /// </summary>");
+
+      for (var i = 0; i < fieldsAndProperties.Count; i++)
+      {
+         var memberInfo = fieldsAndProperties[i];
+
+         _sb.Append(@"
+      /// <param name=""").Append(memberInfo.ArgumentName).Append(@""">The value to be used for object creation.</param>");
+      }
+
+      _sb.Append(@"
+      /// <param name=""obj"">
+      /// When this method returns, contains the created instance of type ").AppendTypeForXmlComment(_state).Append(@"
+      /// if the operation is successful; otherwise, <c>null</c>.
+      /// </param>
+      /// <param name=""validationError"">
+      /// When this method returns, contains the ").AppendTypeForXmlComment(_state.ValidationError).Append(@"
+      /// describing why validation failed, if the operation fails; otherwise, <c>null</c>.
+      /// </param>
+      /// <returns>
+      /// <c>true</c> if the instance is successfully created; otherwise, <c>false</c>.
+      /// </returns>
       public static bool ").Append(_state.Settings.TryCreateFactoryMethodName).Append("(");
 
       _sb.RenderArgumentsWithType(fieldsAndProperties, @"
@@ -199,6 +260,21 @@ private void GenerateValidateMethod()
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Validates the values and creates an instance of type ").AppendTypeForXmlComment(_state).Append(@" if validation is successful.
+      /// </summary>");
+
+      for (var i = 0; i < fieldsAndProperties.Count; i++)
+      {
+         var memberInfo = fieldsAndProperties[i];
+
+         _sb.Append(@"
+      /// <param name=""").Append(memberInfo.ArgumentName).Append(@""">The value to be used for object creation.</param>");
+      }
+
+      _sb.Append(@"
+      /// <param name=""obj"">The created object if validation is successful, otherwise <c>null</c>.</param>
+      /// <returns>A validation error if validation fails; otherwise, <c>null</c>.</returns>
       public static ").AppendTypeFullyQualified(_state.ValidationError).Append("? Validate(");
 
       _sb.RenderArgumentsWithType(fieldsAndProperties, @"
@@ -350,6 +426,9 @@ private void GenerateConstructor()
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Initializes a new instance of the ").AppendTypeForXmlComment(_state).Append(@" type.
+      /// </summary>
       ").RenderAccessModifier(_state.Settings.ConstructorAccessModifier).Append(" ").Append(_state.Name).Append("(");
 
       _sb.RenderArgumentsWithType(fieldsAndProperties, prefix: @"

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/ValueObjects/ComplexValueObjectCodeGenerator.cs

@@ -40,6 +40,9 @@ namespace ").Append(_type.Namespace).Append(@";
 [global::System.Text.Json.Serialization.JsonConverterAttribute(typeof(JsonConverterFactory))]
 partial ").AppendTypeKind(_type).Append(" ").Append(_type.Name).Append(@"
 {
+   /// <summary>
+   /// JSON converter for ").AppendTypeForXmlComment(_type).Append(@".
+   /// </summary>
    public sealed class JsonConverter : global::System.Text.Json.Serialization.JsonConverter<").AppendTypeFullyQualified(_type).Append(@">
    {");
 
@@ -60,6 +63,9 @@ public sealed class JsonConverter : global::System.Text.Json.Serialization.JsonC
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Initializes JSON converter for ").AppendTypeForXmlComment(_type).Append(@".
+      /// </summary>
       public JsonConverter(global::System.Text.Json.JsonSerializerOptions options)
       {
          if(options is null)
@@ -311,6 +317,9 @@ public override void Write(global::System.Text.Json.Utf8JsonWriter writer, ").Ap
       }
    }
 
+   /// <summary>
+   /// JSON converter factory for ").AppendTypeForXmlComment(_type).Append(@".
+   /// </summary>
    public class JsonConverterFactory : global::System.Text.Json.Serialization.JsonConverterFactory
    {
       /// <inheritdoc />

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/ValueObjects/ComplexValueObjectJsonCodeGenerator.cs

@@ -65,6 +65,9 @@ namespace ").Append(_type.Namespace).Append(@";
 [global::MessagePack.MessagePackFormatter(typeof(ValueObjectMessagePackFormatter))]
 partial ").AppendTypeKind(_type).Append(" ").Append(_type.Name).Append(@"
 {
+   /// <summary>
+   /// MassagePack formatter for ").AppendTypeForXmlComment(_type).Append(@".
+   /// </summary>
    public sealed class ValueObjectMessagePackFormatter : global::MessagePack.Formatters.IMessagePackFormatter<").AppendTypeFullyQualifiedNullAnnotated(_type).Append(@">
    {
       /// <inheritdoc />

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/ValueObjects/ComplexValueObjectMessagePackCodeGenerator.cs

@@ -39,6 +39,9 @@ namespace ").Append(_type.Namespace).Append(@";
 [global::Newtonsoft.Json.JsonConverterAttribute(typeof(ValueObjectNewtonsoftJsonConverter))]
 partial ").AppendTypeKind(_type).Append(" ").Append(_type.Name).Append(@"
 {
+   /// <summary>
+   /// JSON converter for ").AppendTypeForXmlComment(_type).Append(@".
+   /// </summary>
    public sealed class ValueObjectNewtonsoftJsonConverter : global::Newtonsoft.Json.JsonConverter
    {
       private static readonly global::System.Type _type = typeof(").AppendTypeFullyQualified(_type).Append(@");

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/ValueObjects/ComplexValueObjectNewtonsoftJsonCodeGenerator.cs

@@ -103,6 +103,9 @@ private void GenerateValueObject(CancellationToken cancellationToken)
       {
          _sb.Append(@"
 
+      /// <summary>
+      /// Default instance of ").AppendTypeForXmlComment(_state).Append(@".
+      /// </summary>
       public static readonly ").AppendTypeFullyQualified(_state).Append(" ").Append(_state.Settings.DefaultInstancePropertyName).Append(" = default;");
       }
 
@@ -272,7 +275,15 @@ private void GenerateConversionFromKey(bool emptyStringYieldsNull)
    private void GenerateCreateMethod(bool allowNullOutput, bool emptyStringYieldsNull)
    {
       _sb.Append(@"
-");
+      /// <summary>
+      /// Creates an instance of the type ").AppendTypeForXmlComment(_state).Append(@" from the provided value,
+      /// performing validation during the process.
+      /// </summary>
+      /// <param name=""").Append(_state.KeyMember.ArgumentName).Append(@""">The value to create the object from.</param>
+      /// <returns>An instance of ").AppendTypeForXmlComment(_state).Append(@" if validation is successful.</returns>
+      /// <exception cref=""System.ComponentModel.DataAnnotations.ValidationException"">
+      /// Thrown if the provided value does not pass validation.
+      /// </exception>");
 
       // If emptyStringYieldsNull=true then an empty-string-argument (i.e. not null) will lead to null as return value,
       // that's why we cannot use the NotNullIfNotNullAttribute.
@@ -298,13 +309,36 @@ private void GenerateTryCreateMethod(bool allowNullOutput, bool emptyStringYield
    {
       _sb.Append(@"
 
+      /// <summary>
+      /// Tries to create an instance of the type ").AppendTypeForXmlComment(_state).Append(@" based on provided value.
+      /// </summary>
+      /// <param name=""").Append(_state.KeyMember.ArgumentName).Append(@""">The value to be used for object creation.</param>
+      /// <param name=""obj"">
+      /// When this method returns, contains the created object if the operation succeeded; otherwise, it will be <c>null</c> or default.
+      /// </param>
+      /// <returns>
+      /// Returns <c>true</c> if the object was successfully created; otherwise, returns <c>false</c>.
+      /// </returns>
       public static bool ").Append(_state.Settings.TryCreateFactoryMethodName).Append("(").RenderArgumentWithType(_state.KeyMember, useNullableTypes: allowNullOutput).Append(emptyStringYieldsNull ? "," : ", [global::System.Diagnostics.CodeAnalysis.NotNullWhen(true)]").Append(" out ").AppendTypeFullyQualifiedNullAnnotated(_state).Append(@" obj)
       {
          return ").Append(_state.Settings.TryCreateFactoryMethodName).Append("(").RenderArgument(_state.KeyMember).Append(@", out obj, out _);
       }");
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Tries to create an instance of the type ").AppendTypeForXmlComment(_state).Append(@" based on provided value.
+      /// </summary>
+      /// <param name=""").Append(_state.KeyMember.ArgumentName).Append(@""">The value to be used for object creation.</param>
+      /// <param name=""obj"">
+      /// When this method returns, contains the created object if the operation succeeded; otherwise, it will be <c>null</c> or default.
+      /// </param>
+      /// <param name=""validationError"">
+      /// When the method returns, contains the validation error if the creation or validation failed; otherwise, it will be <c>null</c>.
+      /// </param>
+      /// <returns>
+      /// Returns <c>true</c> if the object was successfully created; otherwise, returns <c>false</c>.
+      /// </returns>
       public static bool ").Append(_state.Settings.TryCreateFactoryMethodName).Append(@"(
          ").RenderArgumentWithType(_state.KeyMember, useNullableTypes: allowNullOutput).Append(@",
          ").Append(emptyStringYieldsNull ? null : "[global::System.Diagnostics.CodeAnalysis.NotNullWhen(true)] ").Append("out ").AppendTypeFullyQualifiedNullAnnotated(_state).Append(@" obj,
@@ -322,6 +356,15 @@ private void GenerateValidateMethod(bool allowNullKeyMemberInput, bool allowNull
 
       _sb.Append(@"
 
+      /// <summary>
+      /// Validates the provided value and attempts to create an instance of ").AppendTypeForXmlComment(_state).Append(@".
+      /// </summary>
+      /// <param name=""").Append(_state.KeyMember.ArgumentName).Append(@""">The value to validate.</param>
+      /// <param name=""provider"">The format provider for parsing or validation, if applicable.</param>
+      /// <param name=""obj"">When the method returns, contains the created instance of type ").AppendTypeForXmlComment(_state).Append(@" if validation succeeds; otherwise, <c>null</c>.</param>
+      /// <returns>
+      /// A ").AppendTypeForXmlComment(_state.ValidationError).Append(@" representing the validation error if validation fails; otherwise, <c>null</c>.
+      /// </returns>
       public static ").AppendTypeFullyQualified(_state.ValidationError).Append("? Validate(").RenderArgumentWithType(_state.KeyMember, useNullableTypes: allowNullKeyMemberInput).Append(", global::System.IFormatProvider? ").AppendEscaped(providerArgumentName).Append(", out ").AppendTypeFullyQualifiedNullAnnotated(_state).Append(@" obj)
       {");
 
@@ -421,6 +464,9 @@ private void GenerateConstructor()
    {
       _sb.Append(@"
 
+      /// <summary>
+      /// Initializes a new instance of the ").AppendTypeForXmlComment(_state).Append(@" type.
+      /// </summary>
       ").RenderAccessModifier(_state.Settings.ConstructorAccessModifier).Append(" ").Append(_state.Name).Append("(").RenderArgumentWithType(_state.KeyMember).Append(@")
       {
          ValidateConstructorArguments(").RenderArgument(_state.KeyMember, "ref ").Append(@");

src/Thinktecture.Runtime.Extensions.SourceGenerator/CodeAnalysis/ValueObjects/KeyedValueObjectCodeGenerator.cs

@@ -6,7 +6,7 @@ namespace Thinktecture.CodeAnalysis.ValueObjects;
 public sealed class ValueObjectSourceGenerator : ThinktectureSourceGeneratorBase, IIncrementalGenerator
 {
    public ValueObjectSourceGenerator()
-      : base(15_000)
+      : base(18_000)
    {
    }