Add descriptive XML docs for TechnicalData public API

Author: Freezor

FluentAAS/FluentAAS.Templates/TechnicalData/TechnicalDataBuilder.cs

@@ -3,6 +3,11 @@
 
 namespace FluentAAS.Templates.TechnicalData;
 
+/// <summary>
+/// Fluent builder for composing an IDTA Technical Data submodel with typed groups,
+/// ECLASS semantic mapping and IEC 61360-oriented validation.
+/// The builder fails fast so invalid technical parameter sets are rejected during composition.
+/// </summary>
 public sealed class TechnicalDataBuilder
 {
     private readonly IShellBuilder _shellBuilder;
@@ -29,6 +34,13 @@ internal TechnicalDataBuilder(IShellBuilder shellBuilder, string id, string idSh
         _idShort = idShort;
     }
 
+    /// <summary>
+    /// Overrides the submodel identifiers used for the generated Technical Data submodel.
+    /// This allows callers to align the template with project-specific naming and ID strategies.
+    /// </summary>
+    /// <param name="id">Globally unique submodel identifier.</param>
+    /// <param name="idShort">Human-readable short identifier.</param>
+    /// <returns>The current builder for fluent chaining.</returns>
     public TechnicalDataBuilder WithIds(string id, string idShort)
     {
         if (string.IsNullOrWhiteSpace(id))
@@ -46,6 +58,12 @@ public TechnicalDataBuilder WithIds(string id, string idShort)
         return this;
     }
 
+    /// <summary>
+    /// Configures the strongly typed motor performance group.
+    /// Using this method guarantees that only motor-performance properties are assigned in this group.
+    /// </summary>
+    /// <param name="configure">Callback that fills the motor performance properties.</param>
+    /// <returns>The current builder for fluent chaining.</returns>
     public TechnicalDataBuilder WithMotorPerformance(Action<MotorPerformanceGroupBuilder> configure)
     {
         ArgumentNullException.ThrowIfNull(configure);
@@ -56,6 +74,12 @@ public TechnicalDataBuilder WithMotorPerformance(Action<MotorPerformanceGroupBui
         return this;
     }
 
+    /// <summary>
+    /// Configures the strongly typed bearing characteristics group.
+    /// This prevents accidental mixing of unrelated technical parameters.
+    /// </summary>
+    /// <param name="configure">Callback that fills the bearing characteristic properties.</param>
+    /// <returns>The current builder for fluent chaining.</returns>
     public TechnicalDataBuilder WithBearingCharacteristics(Action<BearingCharacteristicsGroupBuilder> configure)
     {
         ArgumentNullException.ThrowIfNull(configure);
@@ -66,6 +90,14 @@ public TechnicalDataBuilder WithBearingCharacteristics(Action<BearingCharacteris
         return this;
     }
 
+    /// <summary>
+    /// Validates and builds the Technical Data submodel, then attaches it to the parent shell.
+    /// This central build step ensures required parameters, units and semantics are validated before persistence.
+    /// </summary>
+    /// <returns>The parent shell builder to continue composing the AAS.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when required properties are missing or semantic mappings are invalid.
+    /// </exception>
     public IShellBuilder BuildTechnicalData()
     {
         ValidateRequiredParameters();
@@ -193,53 +225,117 @@ private sealed record PropertyAssignment(
         string Value,
         string Unit);
 
+    /// <summary>
+    /// Group builder for motor performance properties.
+    /// The API is deliberately constrained to valid motor fields for safer, more predictable template usage.
+    /// </summary>
     public sealed class MotorPerformanceGroupBuilder(TechnicalDataBuilder parent)
     {
+        /// <summary>
+        /// Sets rated voltage with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric rated voltage value.</param>
+        /// <param name="unit">Unit symbol (default: V).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current motor performance builder.</returns>
         public MotorPerformanceGroupBuilder WithRatedVoltage(decimal value, string unit = "V", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.MotorPerformance, TechnicalDataIdentifiers.RatedVoltage, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets rated current with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric rated current value.</param>
+        /// <param name="unit">Unit symbol (default: A).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current motor performance builder.</returns>
         public MotorPerformanceGroupBuilder WithRatedCurrent(decimal value, string unit = "A", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.MotorPerformance, TechnicalDataIdentifiers.RatedCurrent, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets rated power with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric rated power value.</param>
+        /// <param name="unit">Unit symbol (default: kW).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current motor performance builder.</returns>
         public MotorPerformanceGroupBuilder WithRatedPower(decimal value, string unit = "kW", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.MotorPerformance, TechnicalDataIdentifiers.RatedPower, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets rated speed with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric rated speed value.</param>
+        /// <param name="unit">Unit symbol (default: 1/min).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current motor performance builder.</returns>
         public MotorPerformanceGroupBuilder WithRatedSpeed(decimal value, string unit = "1/min", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.MotorPerformance, TechnicalDataIdentifiers.RatedSpeed, value, unit, semanticId);
             return this;
         }
     }
 
+    /// <summary>
+    /// Group builder for bearing characteristics.
+    /// The focused API helps callers provide structurally valid bearing data with consistent semantics.
+    /// </summary>
     public sealed class BearingCharacteristicsGroupBuilder(TechnicalDataBuilder parent)
     {
+        /// <summary>
+        /// Sets bearing inner diameter with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric inner diameter value.</param>
+        /// <param name="unit">Unit symbol (default: mm).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current bearing characteristics builder.</returns>
         public BearingCharacteristicsGroupBuilder WithInnerDiameter(decimal value, string unit = "mm", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.BearingCharacteristics, TechnicalDataIdentifiers.InnerDiameter, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets bearing outer diameter with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric outer diameter value.</param>
+        /// <param name="unit">Unit symbol (default: mm).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current bearing characteristics builder.</returns>
         public BearingCharacteristicsGroupBuilder WithOuterDiameter(decimal value, string unit = "mm", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.BearingCharacteristics, TechnicalDataIdentifiers.OuterDiameter, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets bearing width with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric width value.</param>
+        /// <param name="unit">Unit symbol (default: mm).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current bearing characteristics builder.</returns>
         public BearingCharacteristicsGroupBuilder WithWidth(decimal value, string unit = "mm", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.BearingCharacteristics, TechnicalDataIdentifiers.Width, value, unit, semanticId);
             return this;
         }
 
+        /// <summary>
+        /// Sets bearing limiting speed with IEC 61360-conform unit and optional explicit semantic check.
+        /// </summary>
+        /// <param name="value">Numeric limiting speed value.</param>
+        /// <param name="unit">Unit symbol (default: 1/min).</param>
+        /// <param name="semanticId">Optional ECLASS IRDI for explicit semantic conformity check.</param>
+        /// <returns>The current bearing characteristics builder.</returns>
         public BearingCharacteristicsGroupBuilder WithLimitingSpeed(decimal value, string unit = "1/min", string? semanticId = null)
         {
             parent.UpsertDecimalProperty(TechnicalDataIdentifiers.BearingCharacteristics, TechnicalDataIdentifiers.LimitingSpeed, value, unit, semanticId);

FluentAAS/FluentAAS.Templates/TechnicalData/TechnicalDataCompositionExample.cs

@@ -2,8 +2,17 @@
 
 namespace FluentAAS.Templates.TechnicalData;
 
+/// <summary>
+/// Provides a ready-to-run composition sample for the Technical Data template.
+/// The example demonstrates how to build a complete AAS environment with realistic motor and bearing data.
+/// </summary>
 public static class TechnicalDataCompositionExample
 {
+    /// <summary>
+    /// Builds an example <see cref="IEnvironment"/> containing one shell and one Technical Data submodel.
+    /// Integrators can use this as a reference implementation for production composition flows.
+    /// </summary>
+    /// <returns>A fully built AAS environment with technical parameter groups.</returns>
     public static IEnvironment BuildMotorAndBearingExampleEnvironment()
     {
         var aasBuilder = AasBuilder.Create();

FluentAAS/FluentAAS.Templates/TechnicalData/TechnicalDataIdentifiers.cs

@@ -1,17 +1,58 @@
 namespace FluentAAS.Templates.TechnicalData;
 
+/// <summary>
+/// Provides the canonical <c>idShort</c> values used by the Technical Data builder.
+/// Reusing these identifiers keeps generated structures consistent across projects.
+/// </summary>
 public static class TechnicalDataIdentifiers
 {
+    /// <summary>
+    /// Group identifier for motor performance parameters.
+    /// </summary>
     public const string MotorPerformance = "MotorPerformance";
+
+    /// <summary>
+    /// Group identifier for bearing characteristics.
+    /// </summary>
     public const string BearingCharacteristics = "BearingCharacteristics";
 
+    /// <summary>
+    /// Identifier for rated voltage.
+    /// </summary>
     public const string RatedVoltage = "RatedVoltage";
+
+    /// <summary>
+    /// Identifier for rated current.
+    /// </summary>
     public const string RatedCurrent = "RatedCurrent";
+
+    /// <summary>
+    /// Identifier for rated power.
+    /// </summary>
     public const string RatedPower = "RatedPower";
+
+    /// <summary>
+    /// Identifier for rated speed.
+    /// </summary>
     public const string RatedSpeed = "RatedSpeed";
 
+    /// <summary>
+    /// Identifier for bearing inner diameter.
+    /// </summary>
     public const string InnerDiameter = "InnerDiameter";
+
+    /// <summary>
+    /// Identifier for bearing outer diameter.
+    /// </summary>
     public const string OuterDiameter = "OuterDiameter";
+
+    /// <summary>
+    /// Identifier for bearing width.
+    /// </summary>
     public const string Width = "Width";
+
+    /// <summary>
+    /// Identifier for bearing limiting speed.
+    /// </summary>
     public const string LimitingSpeed = "LimitingSpeed";
 }

FluentAAS/FluentAAS.Templates/TechnicalData/TechnicalDataSemantics.cs

@@ -1,18 +1,54 @@
 namespace FluentAAS.Templates.TechnicalData;
 
+/// <summary>
+/// Provides stable semantic identifiers for the Technical Data template.
+/// Using these constants helps avoid typos and ensures that created AAS elements
+/// are linked to the intended ECLASS/IDTA semantics.
+/// </summary>
 public static class TechnicalDataSemantics
 {
-    // IDTA submodel template semantic ID for Technical Data (v3.0)
+    /// <summary>
+    /// Semantic identifier of the IDTA Technical Data submodel template (v3.0).
+    /// </summary>
     public const string SubmodelTechnicalData = "https://admin-shell.io/idta/TechnicalData/SubmodelTemplate/3/0";
 
-    // ECLASS / IEC 61360 IRDIs used in the predefined catalog.
+    /// <summary>
+    /// ECLASS IRDI for rated voltage.
+    /// </summary>
     public const string RatedVoltage = "0173-1#02-BAF053#008";
+
+    /// <summary>
+    /// ECLASS IRDI for rated current.
+    /// </summary>
     public const string RatedCurrent = "0173-1#02-BAF054#008";
+
+    /// <summary>
+    /// ECLASS IRDI for rated power.
+    /// </summary>
     public const string RatedPower = "0173-1#02-BAF055#008";
+
+    /// <summary>
+    /// ECLASS IRDI for rated speed.
+    /// </summary>
     public const string RatedSpeed = "0173-1#02-BAF056#008";
 
+    /// <summary>
+    /// ECLASS IRDI for bearing inner diameter.
+    /// </summary>
     public const string InnerDiameter = "0173-1#02-AAO677#002";
+
+    /// <summary>
+    /// ECLASS IRDI for bearing outer diameter.
+    /// </summary>
     public const string OuterDiameter = "0173-1#02-AAO678#002";
+
+    /// <summary>
+    /// ECLASS IRDI for bearing width.
+    /// </summary>
     public const string Width = "0173-1#02-AAO679#002";
+
+    /// <summary>
+    /// ECLASS IRDI for bearing limiting speed.
+    /// </summary>
     public const string LimitingSpeed = "0173-1#02-AAO680#002";
 }

FluentAAS/FluentAAS.Templates/TechnicalData/TechnicalDataShellBuilderExtensions.cs

@@ -2,8 +2,20 @@
 
 namespace FluentAAS.Templates.TechnicalData;
 
+/// <summary>
+/// Extension methods to start Technical Data composition directly from a shell builder.
+/// This keeps Technical Data authoring aligned with existing FluentAAS composition workflows.
+/// </summary>
 public static class TechnicalDataShellBuilderExtensions
 {
+    /// <summary>
+    /// Starts a <see cref="TechnicalDataBuilder"/> for the current shell.
+    /// Callers get a focused fluent API that validates technical parameters before they are attached.
+    /// </summary>
+    /// <param name="shellBuilder">The shell that will receive the Technical Data submodel.</param>
+    /// <param name="id">Unique identifier of the Technical Data submodel.</param>
+    /// <param name="idShort">Short readable name of the Technical Data submodel.</param>
+    /// <returns>A specialized technical data builder.</returns>
     public static TechnicalDataBuilder AddTechnicalData(this IShellBuilder shellBuilder, string id, string idShort = "TechnicalData")
     {
         ArgumentNullException.ThrowIfNull(shellBuilder);