Marking Libgpiod v2 api as experimental (#2323)

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 |

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__chips.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class Chip : LibGpiodProxyBase
 {
     private readonly ChipSafeHandle _handle;

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__chip__info.html"/>
+[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.
     /// </summary>
     /// <exception cref="GpiodException">Unexpected error when invoking native function</exception>
+    [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
     public Snapshot MakeSnapshot()
     {
         return new Snapshot(GetName(), GetLabel(), GetNumLines());

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__edge__event.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class EdgeEvent : LibGpiodProxyBase
 {
     private readonly EdgeEventSafeHandle _handle;

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__edge__event.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class EdgeEventBuffer : LibGpiodProxyBase
 {
     internal EdgeEventBufferSafeHandle Handle { get; }

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
 {
     /// <remarks>

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
 {
     /// <summary>

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__line__config.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class LineConfig : LibGpiodProxyBase
 {
     internal LineConfigSafeHandle Handle { get; }

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__line__info.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class LineInfo : LibGpiodProxyBase
 {
     private readonly LineInfoSafeHandle _handle;

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__line__watch.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class LineInfoEvent : LibGpiodProxyBase
 {
     private readonly LineInfoEventSafeHandle _handle;

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__line__request.html#details"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class LineRequest : LibGpiodProxyBase
 {
     private readonly LineRequestSafeHandle _handle;

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__line__watch.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class LineSettings : LibGpiodProxyBase
 {
     internal LineSettingsSafeHandle Handle { get; }

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__misc.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class Miscellaneous
 {
     /// <summary>

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.
 /// </summary>
 /// <seealso href="https://libgpiod.readthedocs.io/en/latest/group__request__config.html"/>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal class RequestConfig : LibGpiodProxyBase
 {
     internal RequestConfigSafeHandle Handle { get; }

src/System.Device.Gpio/System/Device/Gpio/Drivers/Libgpiod/GpiodException.cs

@@ -1,13 +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.Diagnostics.CodeAnalysis;
 using System.IO;
 
 namespace System.Device.Gpio.Drivers;
 
 /// <summary>
 /// Exception in the context of calling libgpiod
 /// </summary>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 public class GpiodException : IOException
 {
     /// <summary>

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
     /// </remarks>
     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.
     }
 
     /// <summary>
@@ -36,6 +39,7 @@ public LibGpiodDriver(int gpioChip = 0)
     /// <param name="gpioChip">The number of the GPIO chip to drive</param>
     /// <param name="driverVersion">Version of the libgpiod driver to create</param>
     /// <remarks>Alternatively, specify the environment variable DOTNET_IOT_LIBGPIOD_DRIVER_VERSION, see documentation</remarks>
+    [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)
     /// <summary>
     /// Version of the libgpiod driver
     /// </summary>
+    [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
     public LibGpiodDriverVersion Version { get; protected set; }
 
     /// <summary>
     /// 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.
     /// </summary>
+    [Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
     public static LibGpiodDriverVersion[] GetAvailableVersions() => LibGpiodDriverFactory.Instance.DriverCandidates;
 
     /// <inheritdoc/>

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;
 /// <summary>
 /// Driver factory for different versions of libgpiod.
 /// </summary>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal sealed class LibGpiodDriverFactory
 {
     private const string DriverVersionEnvVar = "DOTNET_IOT_LIBGPIOD_DRIVER_VERSION";

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;
 
 /// <summary>
 /// Each driver version supports specific libgpiod version/s.
 /// </summary>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 public enum LibGpiodDriverVersion
 {
     /// <summary>

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;
 /// <summary>
 /// Driver that uses libgpiod V2 for GPIO control.
 /// </summary>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal sealed class LibGpiodV2Driver : UnixDriver
 {
     private static readonly string ConsumerId = $"C#-{nameof(LibGpiodV2Driver)}-{Process.GetCurrentProcess().Id}";

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;
 /// <summary>
 /// Class that observes libgpiod line requests for events.
 /// </summary>
+[Experimental(DiagnosticIds.SDGPIO0001, UrlFormat = DiagnosticIds.UrlFormat)]
 internal sealed class LibGpiodV2EventObserver : IDisposable
 {
     private readonly Dictionary<EventSubscription, List<PinChangeEventHandler>> _handlersBySubscription = new();

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)

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)
         {