pepperdash/Essentials
1
0
Fork 0
mirror of https://github.com/PepperDash/Essentials.git synced 2026-02-13 11:44:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: complete XML documentation for all projects with inheritdoc tags

Browse Source 
Co-authored-by: andrew-welker <1765622+andrew-welker@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2025-07-22 15:53:01 +00:00
parent 260677a37f
commit 7987eb8f9b
485 changed files with 8099 additions and 2490 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs
View File

@@ -10,8 +10,8 @@ using System.Threading.Tasks;
namespace PepperDash.Essentials.Core
{
/// <summary>
/// Represents a device that manages room combinations by controlling partitions and scenarios.
/// <summary>
/// Represents a device that manages room combinations by controlling partitions and scenarios.
/// </summary>
/// <remarks>The <see cref="EssentialsRoomCombiner"/> allows for dynamic configuration of room
/// combinations based on partition states and predefined scenarios. It supports both automatic and manual modes
@@ -25,8 +25,8 @@ namespace PepperDash.Essentials.Core
private List<IEssentialsRoom> _rooms;
/// <summary>
/// Gets a list of rooms represented as key-name pairs.
/// <summary>
/// Gets a list of rooms represented as key-name pairs.
/// </summary>
public List<IKeyName> Rooms
{
@@ -38,8 +38,8 @@ namespace PepperDash.Essentials.Core
private bool _isInAutoMode;
/// <summary>
/// Gets or sets a value indicating whether the system is operating in automatic mode.
/// <summary>
/// Gets or sets a value indicating whether the system is operating in automatic mode.
/// </summary>
/// <remarks>Changing this property triggers an update event via
/// <c>IsInAutoModeFeedback.FireUpdate()</c>. Ensure that any event listeners are properly configured to handle
@@ -62,8 +62,8 @@ namespace PepperDash.Essentials.Core
}
}
/// <summary>
/// Gets a value indicating whether automatic mode is disabled.
/// <summary>
/// Gets a value indicating whether automatic mode is disabled.
/// </summary>
public bool DisableAutoMode
{
@@ -79,18 +79,18 @@ namespace PepperDash.Essentials.Core
private Mutex _scenarioChange = new Mutex();
/// <summary>
/// Initializes a new instance of the <see cref="EssentialsRoomCombiner"/> class, which manages room combination
/// scenarios and partition states.
/// </summary>
/// <remarks>The <see cref="EssentialsRoomCombiner"/> class is designed to handle dynamic room
/// combination scenarios based on partition states. It supports both automatic and manual modes for managing
/// room combinations. By default, the instance starts in automatic mode unless the <paramref name="props"/>
/// specifies otherwise. After activation, the room combiner initializes partition state providers and sets up
/// the initial room configuration. Additionally, it subscribes to the <see
/// cref="DeviceManager.AllDevicesInitialized"/> event to ensure proper initialization of dependent devices
/// before determining or setting the room combination scenario.</remarks>
/// <param name="key">The unique identifier for the room combiner instance.</param>
/// <summary>
/// Initializes a new instance of the <see cref="EssentialsRoomCombiner"/> class, which manages room combination
/// scenarios and partition states.
/// </summary>
/// <remarks>The <see cref="EssentialsRoomCombiner"/> class is designed to handle dynamic room
/// combination scenarios based on partition states. It supports both automatic and manual modes for managing
/// room combinations. By default, the instance starts in automatic mode unless the <paramref name="props"/>
/// specifies otherwise. After activation, the room combiner initializes partition state providers and sets up
/// the initial room configuration. Additionally, it subscribes to the <see
/// cref="DeviceManager.AllDevicesInitialized"/> event to ensure proper initialization of dependent devices
/// before determining or setting the room combination scenario.</remarks>
/// <param name="key">The unique identifier for the room combiner instance.</param>
/// <param name="props">The configuration properties for the room combiner, including default settings and debounce times.</param>
public EssentialsRoomCombiner(string key, EssentialsRoomCombinerPropertiesConfig props)
: base(key)
@@ -286,15 +286,15 @@ namespace PepperDash.Essentials.Core
#region IEssentialsRoomCombiner Members
/// <summary>
/// Occurs when the room combination scenario changes.
/// <summary>
/// Occurs when the room combination scenario changes.
/// </summary>
/// <remarks>This event is triggered whenever the configuration or state of the room combination
/// changes. Subscribers can use this event to update their logic or UI based on the new scenario.</remarks>
public event EventHandler<EventArgs> RoomCombinationScenarioChanged;
/// <summary>
/// Gets the current room combination scenario.
/// <summary>
/// Gets the current room combination scenario.
/// </summary>
public IRoomCombinationScenario CurrentScenario
{
@@ -304,24 +304,24 @@ namespace PepperDash.Essentials.Core
}
}
/// <summary>
/// Gets the feedback indicating whether the system is currently in auto mode.
/// <summary>
/// Gets or sets the IsInAutoModeFeedback
/// </summary>
public BoolFeedback IsInAutoModeFeedback { get; private set; }
/// <summary>
/// Enables auto mode for the room combiner and its partitions, allowing automatic room combination scenarios to
/// be determined.
/// <summary>
/// Enables auto mode for the room combiner and its partitions, allowing automatic room combination scenarios to
/// be determined.
/// </summary>
/// <remarks>Auto mode allows the room combiner to automatically adjust its configuration based on
/// the state of its partitions. If auto mode is disabled in the configuration, this method logs a warning and
/// does not enable auto mode.</remarks>
public void SetAutoMode()
{
if(_propertiesConfig.DisableAutoMode)
{
this.LogWarning("Auto mode is disabled for this room combiner. Cannot set to auto mode.");
return;
if(_propertiesConfig.DisableAutoMode)
{
this.LogWarning("Auto mode is disabled for this room combiner. Cannot set to auto mode.");
return;
}
IsInAutoMode = true;
@@ -333,12 +333,15 @@ namespace PepperDash.Essentials.Core
DetermineRoomCombinationScenario();
}
/// <summary>
/// Switches the system to manual mode, disabling automatic operations.
/// <summary>
/// Switches the system to manual mode, disabling automatic operations.
/// </summary>
/// <remarks>This method sets the system to manual mode by updating the mode state and propagates
/// the change to all partitions. Once in manual mode, automatic operations are disabled for the system and its
/// partitions.</remarks>
/// <summary>
/// SetManualMode method
/// </summary>
public void SetManualMode()
{
IsInAutoMode = false;
@@ -349,11 +352,14 @@ namespace PepperDash.Essentials.Core
}
}
/// <summary>
/// Toggles the current mode between automatic and manual.
/// <summary>
/// Toggles the current mode between automatic and manual.
/// </summary>
/// <remarks>If the current mode is automatic, this method switches to manual mode. If the
/// current mode is manual, it switches to automatic mode.</remarks>
/// <summary>
/// ToggleMode method
/// </summary>
public void ToggleMode()
{
if (IsInAutoMode)
@@ -366,21 +372,21 @@ namespace PepperDash.Essentials.Core
}
}
/// <summary>
/// Gets the collection of room combination scenarios.
/// <summary>
/// Gets or sets the RoomCombinationScenarios
/// </summary>
public List<IRoomCombinationScenario> RoomCombinationScenarios { get; private set; }
/// <summary>
/// Gets the collection of partition controllers managed by this instance.
/// <summary>
/// Gets the collection of partition controllers managed by this instance.
/// </summary>
public List<IPartitionController> Partitions { get; private set; }
/// <summary>
/// Toggles the state of the partition identified by the specified partition key.
/// </summary>
/// <remarks>If no partition with the specified key exists, the method performs no
/// action.</remarks>
/// <summary>
/// Toggles the state of the partition identified by the specified partition key.
/// </summary>
/// <remarks>If no partition with the specified key exists, the method performs no
/// action.</remarks>
/// <param name="partitionKey">The key of the partition whose state is to be toggled. This value cannot be null or empty.</param>
public void TogglePartitionState(string partitionKey)
{
@@ -392,16 +398,16 @@ namespace PepperDash.Essentials.Core
}
}
/// <summary>
/// Sets the room combination scenario based on the specified scenario key.
/// </summary>
/// <remarks>This method manually adjusts the partition states according to the specified
/// scenario. If the application is in auto mode, the operation will not proceed, and a log message will be
/// generated indicating that the mode must be set to manual first. If the specified scenario key does not
/// match any existing scenario, a debug log message will be generated. For each partition state in the
/// scenario, the corresponding partition will be updated to either "Present" or "Not Present" based on the
/// scenario's configuration. If a partition key in the scenario cannot be found, a debug log message will be
/// generated.</remarks>
/// <summary>
/// Sets the room combination scenario based on the specified scenario key.
/// </summary>
/// <remarks>This method manually adjusts the partition states according to the specified
/// scenario. If the application is in auto mode, the operation will not proceed, and a log message will be
/// generated indicating that the mode must be set to manual first. If the specified scenario key does not
/// match any existing scenario, a debug log message will be generated. For each partition state in the
/// scenario, the corresponding partition will be updated to either "Present" or "Not Present" based on the
/// scenario's configuration. If a partition key in the scenario cannot be found, a debug log message will be
/// generated.</remarks>
/// <param name="scenarioKey">The key identifying the room combination scenario to apply. This must match the key of an existing scenario.</param>
public void SetRoomCombinationScenario(string scenarioKey)
{
@@ -451,16 +457,19 @@ namespace PepperDash.Essentials.Core
#endregion
}
/// <summary>
/// Provides a factory for creating instances of <see cref="EssentialsRoomCombiner"/> devices.
/// <summary>
/// Provides a factory for creating instances of <see cref="EssentialsRoomCombiner"/> devices.
/// </summary>
/// <remarks>This factory is responsible for constructing <see cref="EssentialsRoomCombiner"/> devices
/// based on the provided configuration. It supports the type name "essentialsroomcombiner" for device
/// creation.</remarks>
/// <summary>
/// Represents a EssentialsRoomCombinerFactory
/// </summary>
public class EssentialsRoomCombinerFactory : EssentialsDeviceFactory<EssentialsRoomCombiner>
{
/// <summary>
/// Initializes a new instance of the <see cref="EssentialsRoomCombinerFactory"/> class.
/// <summary>
/// Initializes a new instance of the <see cref="EssentialsRoomCombinerFactory"/> class.
/// </summary>
/// <remarks>This factory is used to create instances of room combiners with the specified type
/// names. By default, the factory includes the type name "essentialsroomcombiner".</remarks>
@@ -469,13 +478,13 @@ namespace PepperDash.Essentials.Core
TypeNames = new List<string> { "essentialsroomcombiner" };
}
/// <summary>
/// Creates and initializes a new instance of the <see cref="EssentialsRoomCombiner"/> device.
/// </summary>
/// <remarks>This method uses the provided device configuration to extract the properties and
/// create an <see cref="EssentialsRoomCombiner"/> device. Ensure that the configuration contains valid
/// properties for the device to be created successfully.</remarks>
/// <param name="dc">The device configuration containing the key and properties required to build the device.</param>
/// <summary>
/// Creates and initializes a new instance of the <see cref="EssentialsRoomCombiner"/> device.
/// </summary>
/// <remarks>This method uses the provided device configuration to extract the properties and
/// create an <see cref="EssentialsRoomCombiner"/> device. Ensure that the configuration contains valid
/// properties for the device to be created successfully.</remarks>
/// <param name="dc">The device configuration containing the key and properties required to build the device.</param>
/// <returns>A new instance of <see cref="EssentialsRoomCombiner"/> initialized with the specified configuration.</returns>
public override EssentialsDevice BuildDevice(PepperDash.Essentials.Core.Config.DeviceConfig dc)
{

23
src/PepperDash.Essentials.Core/Room/Combining/IEssentialsRoomCombiner.cs
View File

@@ -28,19 +28,19 @@ namespace PepperDash.Essentials.Core
[JsonIgnore]
BoolFeedback IsInAutoModeFeedback {get;}
/// <summary>
/// Gets a value indicating whether the automatic mode is disabled.
/// <summary>
/// Gets a value indicating whether the automatic mode is disabled.
/// </summary>
[JsonProperty("disableAutoMode")]
bool DisableAutoMode { get; }
/// <summary>
/// Gets a value indicating whether the system is operating in automatic mode.
/// <summary>
/// Gets a value indicating whether the system is operating in automatic mode.
/// </summary>
[JsonProperty("isInAutoMode")]
bool IsInAutoMode { get; }
/// <summary>
/// Gets the collection of rooms associated with the current object.
/// <summary>
/// Gets the collection of rooms associated with the current object.
/// </summary>
[JsonProperty("rooms")]
List<IKeyName> Rooms { get; }
@@ -85,13 +85,16 @@ namespace PepperDash.Essentials.Core
void SetRoomCombinationScenario(string scenarioKey);
}
/// <summary>
/// Represents a scenario for combining rooms, including activation, deactivation, and associated state.
/// <summary>
/// Represents a scenario for combining rooms, including activation, deactivation, and associated state.
/// </summary>
/// <remarks>This interface defines the behavior for managing room combination scenarios, including
/// activation and deactivation, tracking the active state, and managing related partition states and UI mappings.
/// Implementations of this interface are expected to handle the logic for room combinations based on the provided
/// partition states and UI mappings.</remarks>
/// <summary>
/// Defines the contract for IRoomCombinationScenario
/// </summary>
public interface IRoomCombinationScenario : IKeyName
{
/// <summary>
@@ -100,8 +103,8 @@ namespace PepperDash.Essentials.Core
[JsonIgnore]
BoolFeedback IsActiveFeedback { get; }
/// <summary>
/// Gets a value indicating whether the entity is active.
/// <summary>
/// Gets a value indicating whether the entity is active.
/// </summary>
[JsonProperty("isActive")]
bool IsActive { get; }

6
src/PepperDash.Essentials.Core/Room/Combining/RoomCombinationScenario.cs
View File

@@ -21,6 +21,9 @@ namespace PepperDash.Essentials.Core
public string Name { get; set; }
[JsonProperty("partitionStates")]
/// <summary>
/// Gets or sets the PartitionStates
/// </summary>
public List<PartitionState> PartitionStates { get; private set; }
[JsonProperty("uiMap")]
@@ -45,6 +48,9 @@ namespace PepperDash.Essentials.Core
}
[JsonIgnore]
/// <summary>
/// Gets or sets the IsActiveFeedback
/// </summary>
public BoolFeedback IsActiveFeedback { get; private set; }
private List<DeviceActionWrapper> activationActions;