diff --git a/Documentation/DiagnosticIDs.md b/Documentation/DiagnosticIDs.md new file mode 100644 index 0000000000..34ea4d42db --- /dev/null +++ b/Documentation/DiagnosticIDs.md @@ -0,0 +1,9 @@ +# Diagnostic IDs + +Some of the APIs in this repository are still in development and may be changed in the future, so they were marked with the Experimental attribute. If you want to consume these APIs and understand the risks, you can disable the diagnostic IDs directly in your project either by adding a diagnostic id to the `NoWarn` property in your project file or by using the `#pragma warning disable` directive in your code. + +## Diagnostic list + +| Diagnostic ID | Description | +| :---------------- | :---------- | +| `SDGPIO0001` | Experimental APIs related to LibGpiod v2 driver used by newer versions of the library | diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Chip.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Chip.cs index 11ef7450bc..062cd5b2a5 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Chip.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Chip.cs @@ -2,8 +2,9 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Collections.Generic; -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// allows callers to retrieve information about each line, watch lines for state changes and make line requests. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class Chip : LibGpiodProxyBase { private readonly ChipSafeHandle _handle; diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/ChipInfo.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/ChipInfo.cs index 053c1aa92d..64d610f6ba 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/ChipInfo.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/ChipInfo.cs @@ -1,8 +1,9 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -11,6 +12,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// The chip info contains all the publicly available information about a chip. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class ChipInfo : LibGpiodProxyBase { private readonly ChipInfoSafeHandle _handle; @@ -62,6 +64,7 @@ public int GetNumLines() /// Helper function for capturing information and creating an immutable snapshot instance. /// /// Unexpected error when invoking native function + [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public Snapshot MakeSnapshot() { return new Snapshot(GetName(), GetLabel(), GetNumLines()); diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEvent.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEvent.cs index 23eeb85b8e..42c996894a 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEvent.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEvent.cs @@ -2,6 +2,7 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// of events are being read. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class EdgeEvent : LibGpiodProxyBase { private readonly EdgeEventSafeHandle _handle; diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEventBuffer.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEventBuffer.cs index c67d547d89..eb80ca214b 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEventBuffer.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/EdgeEventBuffer.cs @@ -2,6 +2,7 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// of events are being read. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class EdgeEventBuffer : LibGpiodProxyBase { internal EdgeEventBufferSafeHandle Handle { get; } diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyBase.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyBase.cs index 0d3d0fdf89..8908ea23dc 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyBase.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyBase.cs @@ -2,10 +2,12 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using System.Runtime.InteropServices; namespace System.Device.Gpio.Libgpiod.V2; +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal abstract class LibGpiodProxyBase : IDisposable { /// diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyFactory.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyFactory.cs index a4106459d0..8b6d9070b2 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyFactory.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LibGpiodProxyFactory.cs @@ -1,12 +1,14 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal static class LibGpiodProxyFactory { /// diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineConfig.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineConfig.cs index 80428230bd..72803e3ca0 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineConfig.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineConfig.cs @@ -2,8 +2,9 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Collections.Generic; -using System.Linq; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Linq; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -20,6 +21,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// If any of the offsets was duplicated, the last one will take precedence. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class LineConfig : LibGpiodProxyBase { internal LineConfigSafeHandle Handle { get; } diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfo.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfo.cs index c14e05231b..d2034d4d78 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfo.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfo.cs @@ -1,8 +1,9 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// The line must be requested to access the line value. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class LineInfo : LibGpiodProxyBase { private readonly LineInfoSafeHandle _handle; diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfoEvent.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfoEvent.cs index 032242ebc5..c11789c5f4 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfoEvent.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineInfoEvent.cs @@ -2,6 +2,7 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -12,6 +13,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// as well as a snapshot of line's status in the form of a line-info object. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class LineInfoEvent : LibGpiodProxyBase { private readonly LineInfoEventSafeHandle _handle; diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineRequest.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineRequest.cs index 1d656c17cc..16e66ad1b5 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineRequest.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineRequest.cs @@ -2,9 +2,10 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Collections.Generic; +using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using System.Linq; using System.Runtime.InteropServices; -using System.Device.Gpio.Drivers; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -16,6 +17,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// This object provides exclusive usage, i.e. reading or setting lines state. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class LineRequest : LibGpiodProxyBase { private readonly LineRequestSafeHandle _handle; diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineSettings.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineSettings.cs index 8d809dfcc4..185e625099 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineSettings.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/LineSettings.cs @@ -2,6 +2,7 @@ // The .NET Foundation licenses this file to you under the MIT license. using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -12,6 +13,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// as well as a snapshot of line's status in the form of a line-info object. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class LineSettings : LibGpiodProxyBase { internal LineSettingsSafeHandle Handle { get; } diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Miscellaneous.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Miscellaneous.cs index c9273e25dc..27b59863ad 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Miscellaneous.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/Miscellaneous.cs @@ -1,8 +1,9 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -11,6 +12,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// Contains functions that are not part of any specific concept. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class Miscellaneous { /// diff --git a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/RequestConfig.cs b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/RequestConfig.cs index 029f865437..a4928f1ee9 100644 --- a/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/RequestConfig.cs +++ b/src/System.Device.Gpio/Interop/Unix/libgpiod/V2/Proxies/RequestConfig.cs @@ -1,8 +1,9 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Runtime.InteropServices; using System.Device.Gpio.Drivers; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; using LibgpiodV2 = Interop.LibgpiodV2; namespace System.Device.Gpio.Libgpiod.V2; @@ -12,6 +13,7 @@ namespace System.Device.Gpio.Libgpiod.V2; /// The mutators don't return error values. If the values are invalid, in general they are silently adjusted to acceptable ranges. /// /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal class RequestConfig : LibGpiodProxyBase { internal RequestConfigSafeHandle Handle { get; } diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/GpiodException.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/GpiodException.cs index 804b1c5a40..d51c9b8790 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/GpiodException.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/GpiodException.cs @@ -1,6 +1,7 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. +using System.Diagnostics.CodeAnalysis; using System.IO; namespace System.Device.Gpio.Drivers; @@ -8,6 +9,7 @@ namespace System.Device.Gpio.Drivers; /// /// Exception in the context of calling libgpiod /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public class GpiodException : IOException { /// diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriver.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriver.cs index d9b5c1beb9..c31dcfdd9b 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriver.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriver.cs @@ -1,6 +1,7 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. +using System.Diagnostics.CodeAnalysis; using System.Threading; namespace System.Device.Gpio.Drivers; @@ -23,9 +24,11 @@ public class LibGpiodDriver : UnixDriver /// public LibGpiodDriver(int gpioChip = 0) { +#pragma warning disable SDGPIO0001 // Suppressing diagnostic for using experimental APIs from this same repository. LibGpiodDriverFactory.VersionedLibgpiodDriver versionedLibgpiodDriver = LibGpiodDriverFactory.Instance.Create(gpioChip); _driver = versionedLibgpiodDriver.LibGpiodDriver; Version = versionedLibgpiodDriver.DriverVersion; +#pragma warning restore SDGPIO0001 // Suppressing diagnostic for using experimental APIs from this same repository. } /// @@ -36,6 +39,7 @@ public LibGpiodDriver(int gpioChip = 0) /// The number of the GPIO chip to drive /// Version of the libgpiod driver to create /// Alternatively, specify the environment variable DOTNET_IOT_LIBGPIOD_DRIVER_VERSION, see documentation + [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public LibGpiodDriver(int gpioChip, LibGpiodDriverVersion driverVersion) { LibGpiodDriverFactory.VersionedLibgpiodDriver versionedLibgpiodDriver = LibGpiodDriverFactory.Instance.Create(gpioChip, driverVersion); @@ -46,12 +50,14 @@ public LibGpiodDriver(int gpioChip, LibGpiodDriverVersion driverVersion) /// /// Version of the libgpiod driver /// + [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public LibGpiodDriverVersion Version { get; protected set; } /// /// A collection of driver versions that correspond to the installed versions of libgpiod on this system. Each driver is dependent /// on specific libgpiod version/s. If the collection is empty, it indicates that libgpiod might not be installed or could not be detected. /// + [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public static LibGpiodDriverVersion[] GetAvailableVersions() => LibGpiodDriverFactory.Instance.DriverCandidates; /// diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverFactory.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverFactory.cs index 8ef851208b..eb4c1083bd 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverFactory.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverFactory.cs @@ -5,6 +5,7 @@ using System.Device.Gpio.Drivers.Libgpiod.V1; using System.Device.Gpio.Drivers.Libgpiod.V2; using System.Device.Gpio.Libgpiod.V2; +using System.Diagnostics.CodeAnalysis; using System.IO; using System.Linq; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Drivers; /// /// Driver factory for different versions of libgpiod. /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal sealed class LibGpiodDriverFactory { private const string DriverVersionEnvVar = "DOTNET_IOT_LIBGPIOD_DRIVER_VERSION"; diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverVersion.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverVersion.cs index 8b124503f5..ad68dd091b 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverVersion.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/LibGpiodDriverVersion.cs @@ -1,11 +1,14 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. +using System.Diagnostics.CodeAnalysis; + namespace System.Device.Gpio.Drivers; /// /// Each driver version supports specific libgpiod version/s. /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] public enum LibGpiodDriverVersion { /// diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2Driver.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2Driver.cs index 4cfcd8c167..21bb2e1870 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2Driver.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2Driver.cs @@ -5,6 +5,7 @@ using System.Device.Gpio.Libgpiod; using System.Device.Gpio.Libgpiod.V2; using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; using System.Linq; using System.Threading; @@ -13,6 +14,7 @@ namespace System.Device.Gpio.Drivers.Libgpiod.V2; /// /// Driver that uses libgpiod V2 for GPIO control. /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal sealed class LibGpiodV2Driver : UnixDriver { private static readonly string ConsumerId = $"C#-{nameof(LibGpiodV2Driver)}-{Process.GetCurrentProcess().Id}"; diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2EventObserver.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2EventObserver.cs index a60ae1c9f7..d907737828 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2EventObserver.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/LibGpiodV2EventObserver.cs @@ -3,6 +3,7 @@ using System.Collections.Generic; using System.Device.Gpio.Libgpiod.V2; +using System.Diagnostics.CodeAnalysis; using System.Linq; using System.Threading; using System.Threading.Tasks; @@ -12,6 +13,7 @@ namespace System.Device.Gpio.Drivers.Libgpiod.V2; /// /// Class that observes libgpiod line requests for events. /// +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal sealed class LibGpiodV2EventObserver : IDisposable { private readonly Dictionary> _handlersBySubscription = new(); diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/Translator.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/Translator.cs index df4377a877..e80ff02a00 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/Translator.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/V2/Translator.cs @@ -1,11 +1,12 @@ // Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. -using System.Device.Gpio.Libgpiod; using System.Device.Gpio.Libgpiod.V2; +using System.Diagnostics.CodeAnalysis; namespace System.Device.Gpio.Drivers.Libgpiod.V2; +[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)] internal static class Translator { public static (GpiodLineDirection? _direction, GpiodLineBias? _bias) Translate(PinMode pinMode) diff --git a/src/System.Device.Gpio/System/Device/Gpio/Drivers/UnixDriver.cs b/src/System.Device.Gpio/System/Device/Gpio/Drivers/UnixDriver.cs index 20f651a5c7..474e9770c2 100644 --- a/src/System.Device.Gpio/System/Device/Gpio/Drivers/UnixDriver.cs +++ b/src/System.Device.Gpio/System/Device/Gpio/Drivers/UnixDriver.cs @@ -34,7 +34,10 @@ public static UnixDriver Create() UnixDriver? driver = null; try { - driver = (UnixDriver)LibGpiodDriverFactory.Instance.Create(0).LibGpiodDriver; +#pragma warning disable SDGPIO0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + driver = + (UnixDriver)LibGpiodDriverFactory.Instance.Create(0).LibGpiodDriver; +#pragma warning restore SDGPIO0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. } catch (PlatformNotSupportedException) { diff --git a/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/DiagnosticIds.cs b/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/DiagnosticIds.cs new file mode 100644 index 0000000000..ffce69397b --- /dev/null +++ b/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/DiagnosticIds.cs @@ -0,0 +1,15 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Text; + +namespace System.Diagnostics.CodeAnalysis +{ + internal static class DiagnosticIds + { + internal const string UrlFormat = "https://aka.ms/dotnet-iot-warnings/{0}"; + internal const string SDGPIO0001 = nameof(SDGPIO0001); + } +} diff --git a/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs b/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs new file mode 100644 index 0000000000..bd646f9d39 --- /dev/null +++ b/src/System.Device.Gpio/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs @@ -0,0 +1,55 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +namespace System.Diagnostics.CodeAnalysis +{ + /// + /// Indicates that an API is experimental and it may change in the future. + /// + /// + /// This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental + /// feature is used. Authors can use this attribute to ship preview features in their assemblies. + /// + [AttributeUsage(AttributeTargets.Assembly | + AttributeTargets.Module | + AttributeTargets.Class | + AttributeTargets.Struct | + AttributeTargets.Enum | + AttributeTargets.Constructor | + AttributeTargets.Method | + AttributeTargets.Property | + AttributeTargets.Field | + AttributeTargets.Event | + AttributeTargets.Interface | + AttributeTargets.Delegate, Inherited = false)] + internal sealed class ExperimentalAttribute : Attribute + { + /// + /// Initializes a new instance of the class, specifying the ID that the compiler will use + /// when reporting a use of the API the attribute applies to. + /// + /// The ID that the compiler will use when reporting a use of the API the attribute applies to. + public ExperimentalAttribute(string diagnosticId) + { + DiagnosticId = diagnosticId; + } + + /// + /// Gets the ID that the compiler will use when reporting a use of the API the attribute applies to. + /// + /// The unique diagnostic ID. + /// + /// The diagnostic ID is shown in build output for warnings and errors. + /// This property represents the unique ID that can be used to suppress the warnings or errors, if needed. + /// + public string DiagnosticId { get; } + + /// + /// Gets or sets the URL for corresponding documentation. + /// The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID. + /// + /// The format string that represents a URL to corresponding documentation. + /// An example format string is https://contoso.com/obsoletion-warnings/{0}. + public string? UrlFormat { get; set; } + } +}