From e0ee5b047499831bafd1f4b9a79d707a12c3ced4 Mon Sep 17 00:00:00 2001 From: Erik Meyer Date: Wed, 28 Jan 2026 16:13:11 -0500 Subject: [PATCH] wip: update XML comments --- .../Secrets/CrestronGlobalSecretsProvider.cs | 4 + .../Secrets/CrestronLocalSecretsProvider.cs | 5 +- .../Secrets/CrestronSecret.cs | 16 +++ .../Secrets/SecretsManager.cs | 6 + .../Secrets/SecretsPropertiesConfig.cs | 7 + .../Shades/Shade Interfaces.cs | 80 ++++++++++- .../Shades/ShadeBase.cs | 20 ++- src/PepperDash.Essentials.Core/SigHelper.cs | 3 +- .../SmartObjects/SmartObjectDPad.cs | 39 ++++-- .../SmartObjects/SmartObjectDynamicList.cs | 58 ++++---- .../SmartObjects/SmartObjectHelperBase.cs | 29 ++-- .../SmartObjects/SmartObjectNumeric.cs | 128 ++++++++++++------ .../SubpageReferenceList.cs | 27 +++- .../SubpageReferenceListItem.cs | 9 ++ 14 files changed, 330 insertions(+), 101 deletions(-) diff --git a/src/PepperDash.Essentials.Core/Secrets/CrestronGlobalSecretsProvider.cs b/src/PepperDash.Essentials.Core/Secrets/CrestronGlobalSecretsProvider.cs index 83d0a0a8..45983b0c 100644 --- a/src/PepperDash.Essentials.Core/Secrets/CrestronGlobalSecretsProvider.cs +++ b/src/PepperDash.Essentials.Core/Secrets/CrestronGlobalSecretsProvider.cs @@ -22,6 +22,10 @@ namespace PepperDash.Essentials.Core /// public string Description { get; private set; } + /// + /// Constructor for CrestronGlobalSecretsProvider + /// + /// The key for the secret provider public CrestronGlobalSecretsProvider(string key) { Key = key; diff --git a/src/PepperDash.Essentials.Core/Secrets/CrestronLocalSecretsProvider.cs b/src/PepperDash.Essentials.Core/Secrets/CrestronLocalSecretsProvider.cs index a20d832e..31a1faa3 100644 --- a/src/PepperDash.Essentials.Core/Secrets/CrestronLocalSecretsProvider.cs +++ b/src/PepperDash.Essentials.Core/Secrets/CrestronLocalSecretsProvider.cs @@ -23,7 +23,10 @@ namespace PepperDash.Essentials.Core /// public string Description { get; private set; } - + /// + /// Constructor for CrestronLocalSecretsProvider + /// + /// The key for the secret provider public CrestronLocalSecretsProvider(string key) { Key = key; diff --git a/src/PepperDash.Essentials.Core/Secrets/CrestronSecret.cs b/src/PepperDash.Essentials.Core/Secrets/CrestronSecret.cs index 27fbcdad..5a606453 100644 --- a/src/PepperDash.Essentials.Core/Secrets/CrestronSecret.cs +++ b/src/PepperDash.Essentials.Core/Secrets/CrestronSecret.cs @@ -11,11 +11,27 @@ namespace PepperDash.Essentials.Core /// public class CrestronSecret : ISecret { + /// + /// Gets the Provider + /// public ISecretProvider Provider { get; private set; } + + /// + /// Gets the Key + /// public string Key { get; private set; } + /// + /// Gets the Value + /// public object Value { get; private set; } + /// + /// Constructor for CrestronSecret + /// + /// key for the secret + /// value of the secret + /// provider of the secret public CrestronSecret(string key, string value, ISecretProvider provider) { Key = key; diff --git a/src/PepperDash.Essentials.Core/Secrets/SecretsManager.cs b/src/PepperDash.Essentials.Core/Secrets/SecretsManager.cs index 6a08f0e2..382f5d55 100644 --- a/src/PepperDash.Essentials.Core/Secrets/SecretsManager.cs +++ b/src/PepperDash.Essentials.Core/Secrets/SecretsManager.cs @@ -7,8 +7,14 @@ using Serilog.Events; namespace PepperDash.Essentials.Core { + /// + /// SecretsManager static class + /// public static class SecretsManager { + /// + /// Gets the Secrets dictionary + /// public static Dictionary Secrets { get; private set; } /// diff --git a/src/PepperDash.Essentials.Core/Secrets/SecretsPropertiesConfig.cs b/src/PepperDash.Essentials.Core/Secrets/SecretsPropertiesConfig.cs index f092d5d3..a5a76074 100644 --- a/src/PepperDash.Essentials.Core/Secrets/SecretsPropertiesConfig.cs +++ b/src/PepperDash.Essentials.Core/Secrets/SecretsPropertiesConfig.cs @@ -14,8 +14,15 @@ namespace PepperDash.Essentials.Core /// public class SecretsPropertiesConfig { + /// + /// Gets or sets the Provider + /// [JsonProperty("provider")] public string Provider { get; set; } + + /// + /// Gets or sets the Key + /// [JsonProperty("key")] public string Key { get; set; } } diff --git a/src/PepperDash.Essentials.Core/Shades/Shade Interfaces.cs b/src/PepperDash.Essentials.Core/Shades/Shade Interfaces.cs index 728a5187..2fb5ffd7 100644 --- a/src/PepperDash.Essentials.Core/Shades/Shade Interfaces.cs +++ b/src/PepperDash.Essentials.Core/Shades/Shade Interfaces.cs @@ -8,6 +8,9 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShades { + /// + /// List of shades controlled by this device + /// List Shades { get; } } @@ -16,17 +19,47 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesOpenCloseStop { + /// + /// Opens the shade + /// void Open(); + + /// + /// Closes the shade + /// void Close(); + + /// + /// Stops the shade + /// void Stop(); } + /// + /// Requirements for a device that implements Open/Close/Stop shade control with presets + /// public interface IShadesOpenClosePreset : IShadesOpenCloseStop { + /// + /// Recalls the preset + /// + /// preset number to recall void RecallPreset(uint presetNumber); + + /// + /// Saves the preset + /// + /// preset number to save void SavePreset(uint presetNumber); + + /// + /// Label for the preset button + /// string StopOrPresetButtonLabel { get; } + /// + /// Event raised when a preset is recalled + /// event EventHandler PresetSaved; } @@ -36,7 +69,14 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesRaiseLowerFeedback { + /// + /// Feedback to indicate if the shade is lowering + /// BoolFeedback ShadeIsLoweringFeedback { get; } + + /// + /// Feedback to indicate if the shade is raising + /// BoolFeedback ShadeIsRaisingFeedback { get; } } @@ -45,7 +85,14 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesOpenClosedFeedback: IShadesOpenCloseStop { + /// + /// Feedback to indicate if the shade is open + /// BoolFeedback ShadeIsOpenFeedback { get; } + + /// + /// Feedback to indicate if the shade is closed + /// BoolFeedback ShadeIsClosedFeedback { get; } } @@ -54,8 +101,19 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesStopOrMove { + /// + /// Raises the shade or stops it if it's already moving + /// void OpenOrStop(); + + /// + /// Lowers the shade or stops it if it's already moving + /// void CloseOrStop(); + + /// + /// Opens, closes, or stops the shade depending on current state + /// void OpenCloseOrStop(); } @@ -64,6 +122,9 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesStopFeedback : IShadesOpenCloseStop { + /// + /// Feedback to indicate if the shade is stopped + /// BoolFeedback IsStoppedFeedback { get; } } @@ -72,6 +133,10 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesPosition { + /// + /// Gets the current position of the shade + /// + /// value of the position to set void SetPosition(ushort value); } @@ -80,18 +145,31 @@ namespace PepperDash.Essentials.Core.Shades /// public interface IShadesFeedback: IShadesPosition, IShadesStopFeedback { + /// + /// Feedback to indicate the current position of the shade + /// IntFeedback PositionFeedback { get; } } /// - /// + /// Feedback for scenes /// public interface ISceneFeedback { + /// + /// Runs the scene + /// void Run(); + + /// + /// Feedback to indicate if all shades are at the scene position + /// BoolFeedback AllAreAtSceneFeedback { get; } } + /// + /// Combines basic shade interfaces for Crestron Basic shades + /// public interface ICrestronBasicShade : IShadesOpenClosedFeedback, IShadesStopOrMove, IShadesFeedback, IShadesRaiseLowerFeedback { diff --git a/src/PepperDash.Essentials.Core/Shades/ShadeBase.cs b/src/PepperDash.Essentials.Core/Shades/ShadeBase.cs index c44abac6..ce5de98d 100644 --- a/src/PepperDash.Essentials.Core/Shades/ShadeBase.cs +++ b/src/PepperDash.Essentials.Core/Shades/ShadeBase.cs @@ -9,10 +9,17 @@ using PepperDash.Essentials.Core.CrestronIO; namespace PepperDash.Essentials.Core.Shades { - + /// + /// Base class for shades + /// [Obsolete("Please use PepperDash.Essentials.Devices.Common, this will be removed in 2.1")] public abstract class ShadeBase : EssentialsDevice, IShadesOpenCloseStop { + /// + /// Constructor + /// + /// key of the shade device + /// name of the shade device public ShadeBase(string key, string name) : base(key, name) { @@ -21,8 +28,19 @@ namespace PepperDash.Essentials.Core.Shades #region iShadesOpenClose Members + /// + /// Opens the shade + /// public abstract void Open(); + + /// + /// Stops the shade + /// public abstract void Stop(); + + /// + /// Closes the shade + /// public abstract void Close(); #endregion diff --git a/src/PepperDash.Essentials.Core/SigHelper.cs b/src/PepperDash.Essentials.Core/SigHelper.cs index fb14df78..df1ad605 100644 --- a/src/PepperDash.Essentials.Core/SigHelper.cs +++ b/src/PepperDash.Essentials.Core/SigHelper.cs @@ -17,7 +17,8 @@ namespace PepperDash.Essentials.Core /// /// Runs action when Sig is pressed /// - /// + /// signal pressed + /// action to run public static void Pressed(Sig sig, Action act) { if (sig.BoolValue) act(); } /// diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDPad.cs b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDPad.cs index 436f00b4..605b2344 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDPad.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDPad.cs @@ -13,27 +13,36 @@ namespace PepperDash.Essentials.Core.SmartObjects /// public class SmartObjectDPad : SmartObjectHelperBase { - /// - /// Gets or sets the SigUp - /// + /// + /// Gets or sets the SigUp + /// public BoolOutputSig SigUp { get { return GetBoolOutputNamed("Up"); } } - /// - /// Gets or sets the SigDown - /// + + /// + /// Gets or sets the SigDown + /// public BoolOutputSig SigDown { get { return GetBoolOutputNamed("Down"); } } - /// - /// Gets or sets the SigLeft - /// + + /// + /// Gets or sets the SigLeft + /// public BoolOutputSig SigLeft { get { return GetBoolOutputNamed("Left"); } } - /// - /// Gets or sets the SigRight - /// + + /// + /// Gets or sets the SigRight + /// public BoolOutputSig SigRight { get { return GetBoolOutputNamed("Right"); } } - /// - /// Gets or sets the SigCenter - /// + + /// + /// Gets or sets the SigCenter + /// public BoolOutputSig SigCenter { get { return GetBoolOutputNamed("Center"); } } + /// + /// Constructor + /// + /// smart object + /// use user object handler if true public SmartObjectDPad(SmartObject so, bool useUserObjectHandler) : base(so, useUserObjectHandler) { diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDynamicList.cs b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDynamicList.cs index 2080a07e..fdf7dc04 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDynamicList.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectDynamicList.cs @@ -17,14 +17,24 @@ namespace PepperDash.Essentials.Core.SmartObjects /// public class SmartObjectDynamicList : SmartObjectHelperBase { + /// + /// Sig name for Scroll To Item + /// public const string SigNameScrollToItem = "Scroll To Item"; + + /// + /// Sig name for Set Number of Items + /// public const string SigNameSetNumberOfItems = "Set Number of Items"; - /// - /// Gets or sets the NameSigOffset - /// + /// + /// Gets or sets the NameSigOffset + /// public uint NameSigOffset { get; private set; } + /// + /// Gets or sets the Count + /// public ushort Count { get @@ -34,9 +44,9 @@ namespace PepperDash.Essentials.Core.SmartObjects set { SmartObject.UShortInput[SigNameSetNumberOfItems].UShortValue = value; } } - /// - /// Gets or sets the MaxCount - /// + /// + /// Gets or sets the MaxCount + /// public int MaxCount { get; private set; } /// @@ -62,9 +72,9 @@ namespace PepperDash.Essentials.Core.SmartObjects } } - /// - /// SetItem method - /// + /// + /// SetItem method + /// public void SetItem(uint index, string mainText, string iconName, Action action) { SetItemMainText(index, mainText); @@ -83,9 +93,9 @@ namespace PepperDash.Essentials.Core.SmartObjects //} } - /// - /// SetItemMainText method - /// + /// + /// SetItemMainText method + /// public void SetItemMainText(uint index, string text) { if (index > MaxCount) return; @@ -93,27 +103,27 @@ namespace PepperDash.Essentials.Core.SmartObjects (SmartObject.Device as BasicTriList).StringInput[NameSigOffset + index].StringValue = text; } - /// - /// SetItemIcon method - /// + /// + /// SetItemIcon method + /// public void SetItemIcon(uint index, string iconName) { if (index > MaxCount) return; SmartObject.StringInput[string.Format("Set Item {0} Icon Serial", index)].StringValue = iconName; } - /// - /// SetItemButtonAction method - /// + /// + /// SetItemButtonAction method + /// public void SetItemButtonAction(uint index, Action action) { if (index > MaxCount) return; SmartObject.BooleanOutput[string.Format("Item {0} Pressed", index)].UserObject = action; } - /// - /// SetFeedback method - /// + /// + /// SetFeedback method + /// public void SetFeedback(uint index, bool interlocked) { if (interlocked) @@ -121,9 +131,9 @@ namespace PepperDash.Essentials.Core.SmartObjects SmartObject.BooleanInput[string.Format("Item {0} Selected", index)].BoolValue = true; } - /// - /// ClearFeedbacks method - /// + /// + /// ClearFeedbacks method + /// public void ClearFeedbacks() { for(int i = 1; i<= Count; i++) diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectHelperBase.cs b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectHelperBase.cs index 031259b0..a86687aa 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectHelperBase.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectHelperBase.cs @@ -11,21 +11,26 @@ using Serilog.Events; namespace PepperDash.Essentials.Core.SmartObjects { - /// - /// Represents a SmartObjectHelperBase - /// + /// + /// Represents a SmartObjectHelperBase + /// public class SmartObjectHelperBase { - /// - /// Gets or sets the SmartObject - /// + /// + /// Gets or sets the SmartObject + /// public SmartObject SmartObject { get; private set; } - /// - /// Gets or sets the Validated - /// + /// + /// Gets or sets the Validated + /// public bool Validated { get; protected set; } + /// + /// Constructor + /// + /// smart object + /// use the user object hadnler if true public SmartObjectHelperBase(SmartObject so, bool useUserObjectHandler) { SmartObject = so; @@ -37,6 +42,9 @@ namespace PepperDash.Essentials.Core.SmartObjects } } + /// + /// Destructor + /// ~SmartObjectHelperBase() { SmartObject.SigChange -= this.SmartObject_SigChange; @@ -47,9 +55,6 @@ namespace PepperDash.Essentials.Core.SmartObjects /// /// /// - /// - /// GetBoolOutputNamed method - /// public BoolOutputSig GetBoolOutputNamed(string name) { if (SmartObject.BooleanOutput.Contains(name)) diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectNumeric.cs b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectNumeric.cs index 493fd213..2b6e06b8 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectNumeric.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SmartObjectNumeric.cs @@ -8,52 +8,90 @@ using Crestron.SimplSharpPro.DeviceSupport; namespace PepperDash.Essentials.Core.SmartObjects { - /// - /// Represents a SmartObjectNumeric - /// + /// + /// Represents a SmartObjectNumeric + /// public class SmartObjectNumeric : SmartObjectHelperBase - { - /// - /// Gets or sets the Misc1SigName - /// - public string Misc1SigName { get; set; } - /// - /// Gets or sets the Misc2SigName - /// - public string Misc2SigName { get; set; } + { + /// + /// Gets or sets the Misc1SigName + /// + public string Misc1SigName { get; set; } - public BoolOutputSig Digit1 { get { return GetBoolOutputNamed("1"); } } - public BoolOutputSig Digit2 { get { return GetBoolOutputNamed("2"); } } - public BoolOutputSig Digit3 { get { return GetBoolOutputNamed("3"); } } - public BoolOutputSig Digit4 { get { return GetBoolOutputNamed("4"); } } - /// - /// Gets or sets the Digit5 - /// - public BoolOutputSig Digit5 { get { return GetBoolOutputNamed("5"); } } - public BoolOutputSig Digit6 { get { return GetBoolOutputNamed("6"); } } - public BoolOutputSig Digit7 { get { return GetBoolOutputNamed("7"); } } - public BoolOutputSig Digit8 { get { return GetBoolOutputNamed("8"); } } - /// - /// Gets or sets the Digit9 - /// - public BoolOutputSig Digit9 { get { return GetBoolOutputNamed("9"); } } - /// - /// Gets or sets the Digit0 - /// - public BoolOutputSig Digit0 { get { return GetBoolOutputNamed("0"); } } - /// - /// Gets or sets the Misc1 - /// - public BoolOutputSig Misc1 { get { return GetBoolOutputNamed(Misc1SigName); } } - /// - /// Gets or sets the Misc2 - /// - public BoolOutputSig Misc2 { get { return GetBoolOutputNamed(Misc2SigName); } } + /// + /// Gets or sets the Misc2SigName + /// + public string Misc2SigName { get; set; } - public SmartObjectNumeric(SmartObject so, bool useUserObjectHandler) : base(so, useUserObjectHandler) - { - Misc1SigName = "Misc_1"; - Misc2SigName = "Misc_2"; - } - } + /// + /// Gets or sets the Digit1 + /// + public BoolOutputSig Digit1 { get { return GetBoolOutputNamed("1"); } } + + /// + /// Gets or sets the Digit2 + /// + public BoolOutputSig Digit2 { get { return GetBoolOutputNamed("2"); } } + + /// + /// Gets or sets the Digit3 + /// + public BoolOutputSig Digit3 { get { return GetBoolOutputNamed("3"); } } + + /// + /// Gets or sets the Digit4 + /// + public BoolOutputSig Digit4 { get { return GetBoolOutputNamed("4"); } } + + /// + /// Gets or sets the Digit5 + /// + public BoolOutputSig Digit5 { get { return GetBoolOutputNamed("5"); } } + + /// + /// Gets or sets the Digit6 + /// + public BoolOutputSig Digit6 { get { return GetBoolOutputNamed("6"); } } + + /// + /// Gets or sets the Digit7 + /// + public BoolOutputSig Digit7 { get { return GetBoolOutputNamed("7"); } } + + /// + /// Gets or sets the Digit8 + /// + public BoolOutputSig Digit8 { get { return GetBoolOutputNamed("8"); } } + + /// + /// Gets or sets the Digit9 + /// + public BoolOutputSig Digit9 { get { return GetBoolOutputNamed("9"); } } + + /// + /// Gets or sets the Digit0 + /// + public BoolOutputSig Digit0 { get { return GetBoolOutputNamed("0"); } } + + /// + /// Gets or sets the Misc1 + /// + public BoolOutputSig Misc1 { get { return GetBoolOutputNamed(Misc1SigName); } } + + /// + /// Gets or sets the Misc2 + /// + public BoolOutputSig Misc2 { get { return GetBoolOutputNamed(Misc2SigName); } } + + /// + /// Constructor + /// + /// smart object + /// use user handler if true + public SmartObjectNumeric(SmartObject so, bool useUserObjectHandler) : base(so, useUserObjectHandler) + { + Misc1SigName = "Misc_1"; + Misc2SigName = "Misc_2"; + } + } } \ No newline at end of file diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceList.cs b/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceList.cs index e82c3a63..4ed42d49 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceList.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceList.cs @@ -30,35 +30,60 @@ namespace PepperDash.Essentials.Core /// public class SubpageReferenceList { - + /// + /// Gets or sets the Count + /// public ushort Count { get { return SetNumberOfItemsSig.UShortValue; } set { SetNumberOfItemsSig.UShortValue = value; } } + + /// + /// Gets or sets the MaxDefinedItems + /// public ushort MaxDefinedItems { get; private set; } /// /// Gets or sets the ScrollToItemSig /// public UShortInputSig ScrollToItemSig { get; private set; } + UShortInputSig SetNumberOfItemsSig; + /// /// Gets or sets the BoolIncrement /// public uint BoolIncrement { get; protected set; } + /// /// Gets or sets the UShortIncrement /// public uint UShortIncrement { get; protected set; } + /// /// Gets or sets the StringIncrement /// public uint StringIncrement { get; protected set; } + /// + /// Gets or sets the SRL + /// protected readonly SmartObject SRL; + + /// + /// Gets the list of items in the SRL + /// protected readonly List Items = new List(); + /// + /// Constructor + /// + /// trilist for the smart object + /// smart object ID + /// + /// + /// public SubpageReferenceList(BasicTriListWithSmartObject triList, uint smartObjectId, uint boolIncrement, uint ushortIncrement, uint stringIncrement) { diff --git a/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceListItem.cs b/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceListItem.cs index 4e979a69..e29d0894 100644 --- a/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceListItem.cs +++ b/src/PepperDash.Essentials.Core/SmartObjects/SubpageReferencList/SubpageReferenceListItem.cs @@ -17,8 +17,17 @@ namespace PepperDash.Essentials.Core /// The list that this lives in /// protected SubpageReferenceList Owner; + + /// + /// The index of this item + /// protected uint Index; + /// + /// Constructor + /// + /// index of the item + /// owner of the item public SubpageReferenceListItem(uint index, SubpageReferenceList owner) { Index = index;