From c8ce8cfd0f296a187399f77766d9ffb2cf0f11d0 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Fri, 27 Mar 2026 11:15:08 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`12-enab?= =?UTF-8?q?le-incremental-submodel-composition-via-addsubmodel-at-any-stag?= =?UTF-8?q?e-of-the-build-process`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @Freezor. * https://github.com/Freezor/FluentAAS/pull/20#issuecomment-4141821968 The following files were modified: * `FluentAAS/FluentAAS.Builder/AasBuilder.cs` * `FluentAAS/FluentAAS.Builder/IAasBuilder.cs` * `FluentAAS/FluentAAS.Builder/SubModel/SubmodelFragmentBuilder.cs` --- FluentAAS/FluentAAS.Builder/AasBuilder.cs | 54 +++++++++++++++++-- FluentAAS/FluentAAS.Builder/IAasBuilder.cs | 39 ++++++++++++-- .../SubModel/SubmodelFragmentBuilder.cs | 27 +++++++++- 3 files changed, 111 insertions(+), 9 deletions(-) diff --git a/FluentAAS/FluentAAS.Builder/AasBuilder.cs b/FluentAAS/FluentAAS.Builder/AasBuilder.cs index 3ded557..909dfac 100644 --- a/FluentAAS/FluentAAS.Builder/AasBuilder.cs +++ b/FluentAAS/FluentAAS.Builder/AasBuilder.cs @@ -43,7 +43,14 @@ internal AasBuilder() /// /// /// Thrown when or is null, empty, or whitespace. - /// + /// + /// Begins registering a new Asset Administration Shell with the specified identifier and short name. + /// + /// The unique identifier for the shell; must not be null, empty, or whitespace. + /// A short, human-readable name for the shell; must not be null, empty, or whitespace. + /// The asset kind for the shell's AssetInformation. Defaults to . + /// An to configure the created shell. + /// Thrown when or is null, empty, or whitespace. public IShellBuilder AddShell(string id, string idShort, AssetKind kind = AssetKind.Instance) { if (string.IsNullOrWhiteSpace(id)) @@ -78,7 +85,13 @@ public IShellBuilder AddShell(string id, string idShort, AssetKind kind = AssetK /// Thrown when is null. /// /// Thrown when required submodel fields are invalid. - /// + /// + /// Registers the given submodel with the builder after validating its identifiers. + /// + /// The submodel to add; must have a non-empty `Id` and `IdShort`. + /// The same builder instance for fluent chaining. + /// Thrown if is null. + /// Thrown if the submodel's `Id` or `IdShort` is null, empty, or whitespace. public IAasBuilder AddSubmodel(Submodel submodel) { ValidateSubmodelForPublicAdd(submodel); @@ -91,7 +104,13 @@ public IAasBuilder AddSubmodel(Submodel submodel) /// /// The submodel instance to add. /// The current instance for fluent chaining. + /// + /// Registers an existing instance with the builder without requiring an IdShort value. + /// + /// The submodel to register; its Id must be set (non-empty). + /// The current builder instance for fluent chaining. /// Thrown when is null. + /// Thrown when has a null, empty, or whitespace Id. public IAasBuilder AddExistingSubmodel(Submodel submodel) { AddSubmodelInternal(submodel); @@ -106,6 +125,13 @@ public IAasBuilder AddExistingSubmodel(Submodel submodel) /// Callback that contributes submodel elements. /// The current instance for fluent chaining. /// Thrown when is null, empty, or whitespace. + /// + /// Stages a submodel fragment configuration to be applied to the submodel with the specified id during Build. + /// + /// Identifier of the target submodel; must not be null, empty, or whitespace. + /// Callback that receives a to configure the fragment. + /// The current instance for fluent chaining. + /// Thrown when is null, empty, or whitespace. /// Thrown when is null. public IAasBuilder AddSubmodelFragment(string submodelId, Action configure) { @@ -131,7 +157,14 @@ public IAasBuilder AddSubmodelFragment(string submodelId, Action /// A new containing the configured asset administration /// shells and submodels. - /// + /// + /// Builds an Environment containing the builder's registered shells and submodels after applying any staged submodel fragments and validating build-time invariants. + /// + /// An Environment with copies of the registered AssetAdministrationShells and Submodels. + /// Thrown when one or more duplicate submodel ids are detected among registered Submodel instances. + /// Thrown when a staged submodel fragment references a base submodel id that has not been added. + /// Thrown when a shell contains a submodel reference without a valid identifier. + /// Thrown when a shell references a submodel id that is not present among the registered submodels. public IEnvironment Build() { var duplicateSubmodelIds = _submodels.OfType() @@ -210,6 +243,10 @@ public void AddShellInternal(AssetAdministrationShell shell) /// Intended for internal use by shell or submodel builders. /// /// The submodel instance to add. + /// + /// Registers the given submodel in the builder's internal collection if the same instance is not already present. + /// + /// The submodel to register; must not be null and must have a non-empty Id. /// Thrown when is null. public void AddSubmodelInternal(Submodel submodel) { @@ -222,6 +259,12 @@ public void AddSubmodelInternal(Submodel submodel) } } + /// + /// Validates that the provided is not null and has a non-empty Id. + /// + /// The submodel to validate; its Id must not be null, empty, or whitespace. + /// Thrown when is null. + /// Thrown when 's Id is null, empty, or consists only of whitespace. private static void ValidateSubmodelId(Submodel submodel) { ArgumentNullException.ThrowIfNull(submodel); @@ -232,6 +275,11 @@ private static void ValidateSubmodelId(Submodel submodel) } } + /// + /// Validates that a submodel has a non-empty identifier and a non-empty IdShort. + /// + /// The submodel to validate; its identifier and IdShort must be set. + /// Thrown when submodel.IdShort is null, empty, or whitespace. private static void ValidateSubmodelForPublicAdd(Submodel submodel) { ValidateSubmodelId(submodel); diff --git a/FluentAAS/FluentAAS.Builder/IAasBuilder.cs b/FluentAAS/FluentAAS.Builder/IAasBuilder.cs index e3dc80b..d409809 100644 --- a/FluentAAS/FluentAAS.Builder/IAasBuilder.cs +++ b/FluentAAS/FluentAAS.Builder/IAasBuilder.cs @@ -19,7 +19,14 @@ public interface IAasBuilder /// /// /// Thrown when or is null, empty, or whitespace. - /// + /// +/// Declares a new AssetAdministrationShell to add to the environment. +/// +/// Unique identifier of the shell. +/// Short name (IdShort) for the shell. +/// Specifies the asset kind; defaults to AssetKind.Instance. +/// An IShellBuilder for configuring the newly declared shell. +/// Thrown when or is null, empty, or consists only of whitespace. IShellBuilder AddShell(string id, string idShort, AssetKind kind = AssetKind.Instance); /// @@ -31,7 +38,13 @@ public interface IAasBuilder /// Thrown when is null. /// /// Thrown when required submodel fields (for example ) are invalid. - /// + /// +/// Registers a fully constructed Submodel with the builder so it becomes part of the resulting environment. +/// +/// The fully constructed Submodel to register; it will participate in build-time uniqueness validation. +/// The same IAasBuilder instance for fluent chaining. +/// Thrown when is null. +/// Thrown when required submodel fields (for example, IReferable.IdShort) are null, empty, or otherwise invalid. IAasBuilder AddSubmodel(Submodel submodel); /// @@ -39,7 +52,12 @@ public interface IAasBuilder /// /// The submodel instance to add. /// The current instance for fluent chaining. - /// Thrown when is null. + /// +/// Adds an existing Submodel instance to the builder's configuration. +/// +/// The Submodel instance to add to the environment. +/// The current instance for fluent chaining. +/// Thrown when is null. IAasBuilder AddExistingSubmodel(Submodel submodel); /// @@ -50,7 +68,14 @@ public interface IAasBuilder /// Callback that contributes submodel elements. /// The current instance for fluent chaining. /// Thrown when is null, empty, or whitespace. - /// Thrown when is null. + /// +/// Register a staged submodel fragment to be applied to an existing submodel identified by during Build. +/// +/// The identifier of an already registered submodel to which the fragment will be applied. +/// An action that configures the staged fragment using a ; fragments are applied in registration order when Build is called. +/// The same instance for fluent chaining. +/// Thrown when is null, empty, or whitespace. +/// Thrown when is null. IAasBuilder AddSubmodelFragment(string submodelId, Action configure); /// @@ -75,6 +100,10 @@ public interface IAasBuilder /// Intended for internal use by shell or submodel builders. /// /// The submodel instance to add. - /// Thrown when is null. + /// +/// Adds a fully constructed Submodel to the builder's environment. +/// +/// The fully constructed Submodel to add to the environment. +/// Thrown when is null. void AddSubmodelInternal(Submodel submodel); } diff --git a/FluentAAS/FluentAAS.Builder/SubModel/SubmodelFragmentBuilder.cs b/FluentAAS/FluentAAS.Builder/SubModel/SubmodelFragmentBuilder.cs index df998e6..c37bb34 100644 --- a/FluentAAS/FluentAAS.Builder/SubModel/SubmodelFragmentBuilder.cs +++ b/FluentAAS/FluentAAS.Builder/SubModel/SubmodelFragmentBuilder.cs @@ -8,6 +8,11 @@ public sealed class SubmodelFragmentBuilder { private readonly Submodel _target; + /// + /// Initializes a SubmodelFragmentBuilder for the specified submodel and ensures its SubmodelElements collection is initialized. + /// + /// The submodel to which staged elements will be appended. + /// Thrown if is null. internal SubmodelFragmentBuilder(Submodel target) { _target = target ?? throw new ArgumentNullException(nameof(target)); @@ -23,7 +28,15 @@ internal SubmodelFragmentBuilder(Submodel target) /// The current . /// /// Thrown when or is null, empty, or whitespace. - /// + /// + /// Adds a Property with the specified idShort, value, and data type to the target Submodel. + /// + /// Short identifier for the Property; must not be null, empty, or whitespace. + /// Value for the Property; must not be null, empty, or whitespace. + /// Data type for the Property value. Defaults to . + /// The current instance for fluent chaining. + /// Thrown when is null, empty, or whitespace. + /// Thrown when is null, empty, or whitespace. public SubmodelFragmentBuilder AddProperty(string idShort, string value, DataTypeDefXsd valueType = DataTypeDefXsd.String) { if (string.IsNullOrWhiteSpace(idShort)) @@ -53,6 +66,13 @@ public SubmodelFragmentBuilder AddProperty(string idShort, string value, DataTyp /// Configuration callback for language strings. /// The current . /// Thrown when is null, empty, or whitespace. + /// + /// Adds a multilingual (language-string) property to the target submodel and stages it for later build operations. + /// + /// The short identifier for the property; must not be null, empty, or whitespace. + /// A configuration callback that populates the with language entries. + /// The current instance for fluent chaining. + /// Thrown when is null, empty, or consists only of whitespace. /// Thrown when is null. public SubmodelFragmentBuilder AddMultiLanguageProperty(string idShort, Action configure) { @@ -75,6 +95,11 @@ public SubmodelFragmentBuilder AddMultiLanguageProperty(string idShort, Action /// The submodel element to add. /// The current . + /// + /// Appends a submodel element to the target submodel and returns this builder for chaining. + /// + /// The submodel element to add to the target submodel. + /// The current instance. /// Thrown when is null. public SubmodelFragmentBuilder AddElement(ISubmodelElement element) {