Add [Experimental] to converter-related APIs (#5668)

Closes #5620 (cherry picked from commit c86e5ef)
npgsql · Apr 12, 2024 · 4e5fb5a · 4e5fb5a
1 parent 6927b98
commit 4e5fb5a
Show file tree

Hide file tree

Showing 34 changed files with 91 additions and 2 deletions.
diff --git a/src/Npgsql.GeoJSON/Npgsql.GeoJSON.csproj b/src/Npgsql.GeoJSON/Npgsql.GeoJSON.csproj
@@ -5,6 +5,7 @@
     <PackageTags>npgsql;postgresql;postgres;postgis;geojson;spatial;ado;ado.net;database;sql</PackageTags>
     <TargetFramework>netstandard2.0</TargetFramework>
     <TargetFramework Condition="'$(DeveloperBuild)' == 'True'">net8.0</TargetFramework>
+    <NoWarn>$(NoWarn);NPG9001</NoWarn> <!-- Converter-related APIs are experimental -->
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Npgsql.Json.NET/Npgsql.Json.NET.csproj b/src/Npgsql.Json.NET/Npgsql.Json.NET.csproj
@@ -6,6 +6,7 @@
     <TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
     <TargetFrameworks Condition="'$(DeveloperBuild)' == 'True'">net8.0</TargetFrameworks>
     <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn);NPG9001</NoWarn> <!-- Converter-related APIs are experimental -->
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Npgsql.NetTopologySuite/Npgsql.NetTopologySuite.csproj b/src/Npgsql.NetTopologySuite/Npgsql.NetTopologySuite.csproj
@@ -7,6 +7,7 @@
     <TargetFramework>netstandard2.0</TargetFramework>
     <TargetFramework Condition="'$(DeveloperBuild)' == 'True'">net8.0</TargetFramework>
     <NoWarn>$(NoWarn);NU5104</NoWarn>
+    <NoWarn>$(NoWarn);NPG9001</NoWarn> <!-- Converter-related APIs are experimental -->
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Npgsql.NodaTime/Npgsql.NodaTime.csproj b/src/Npgsql.NodaTime/Npgsql.NodaTime.csproj
@@ -6,6 +6,7 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <TargetFrameworks Condition="'$(DeveloperBuild)' != 'True'">netstandard2.0;net6.0</TargetFrameworks>
     <TargetFrameworks Condition="'$(DeveloperBuild)' == 'True'">net8.0</TargetFrameworks>
+    <NoWarn>$(NoWarn);NPG9001</NoWarn> <!-- Converter-related APIs are experimental -->
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Npgsql/Internal/BufferRequirements.cs b/src/Npgsql/Internal/BufferRequirements.cs
@@ -1,7 +1,9 @@
 using System;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct BufferRequirements : IEquatable<BufferRequirements>
 {
     readonly Size _read;

diff --git a/src/Npgsql/Internal/DataFormat.cs b/src/Npgsql/Internal/DataFormat.cs
@@ -1,8 +1,10 @@
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public enum DataFormat : byte
 {
     Binary,

diff --git a/src/Npgsql/Internal/DynamicTypeInfoResolver.cs b/src/Npgsql/Internal/DynamicTypeInfoResolver.cs
@@ -6,6 +6,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 [RequiresDynamicCode("A dynamic type info resolver may need to construct a generic converter for a statically unknown type.")]
 public abstract class DynamicTypeInfoResolver : IPgTypeInfoResolver
 {

diff --git a/src/Npgsql/Internal/HackyEnumTypeMapping.cs b/src/Npgsql/Internal/HackyEnumTypeMapping.cs
@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Reflection;
 using Npgsql.Internal;
@@ -13,6 +14,7 @@ namespace Npgsql.Internal;
 /// <summary>
 /// Hacky temporary measure used by EFCore.PG to extract user-configured enum mappings. Accessed via reflection only.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public sealed class HackyEnumTypeMapping
 {
     public HackyEnumTypeMapping(Type enumClrType, string pgTypeName, INpgsqlNameTranslator nameTranslator)

diff --git a/src/Npgsql/Internal/INpgsqlDatabaseInfoFactory.cs b/src/Npgsql/Internal/INpgsqlDatabaseInfoFactory.cs
@@ -1,4 +1,5 @@
-using System.Threading.Tasks;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading.Tasks;
 using Npgsql.Util;
 
 namespace Npgsql.Internal;
@@ -8,6 +9,7 @@ namespace Npgsql.Internal;
 /// and the types it contains. When first connecting to a database, Npgsql will attempt to load information
 /// about it via this factory.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public interface INpgsqlDatabaseInfoFactory
 {
     /// <summary>
@@ -19,4 +21,4 @@ public interface INpgsqlDatabaseInfoFactory
     /// database isn't of the correct type and isn't handled by this factory.
     /// </returns>
     Task<NpgsqlDatabaseInfo?> Load(NpgsqlConnector conn, NpgsqlTimeout timeout, bool async);
-}
+}
diff --git a/src/Npgsql/Internal/IPgTypeInfoResolver.cs b/src/Npgsql/Internal/IPgTypeInfoResolver.cs
@@ -1,11 +1,13 @@
 using System;
+using System.Diagnostics.CodeAnalysis;
 using Npgsql.Internal.Postgres;
 
 namespace Npgsql.Internal;
 
 /// <summary>
 /// An Npgsql resolver for type info. Used by Npgsql to read and write values to PostgreSQL.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public interface IPgTypeInfoResolver
 {
     /// <summary>

diff --git a/src/Npgsql/Internal/NpgsqlConnector.cs b/src/Npgsql/Internal/NpgsqlConnector.cs
@@ -3,6 +3,7 @@
 using System.Collections.Generic;
 using System.Data;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Net;
 using System.Net.Security;
@@ -29,6 +30,7 @@ namespace Npgsql.Internal;
 /// Represents a connection to a PostgreSQL backend. Unlike NpgsqlConnection objects, which are
 /// exposed to users, connectors are internal to Npgsql and are recycled by the connection pool.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public sealed partial class NpgsqlConnector
 {
     #region Fields and Properties

diff --git a/src/Npgsql/Internal/NpgsqlDatabaseInfo.cs b/src/Npgsql/Internal/NpgsqlDatabaseInfo.cs
@@ -12,6 +12,7 @@ namespace Npgsql.Internal;
 /// Base class for implementations which provide information about PostgreSQL and PostgreSQL-like databases
 /// (e.g. type definitions, capabilities...).
 /// </summary>
+[Experimental(NpgsqlDiagnostics.DatabaseInfoExperimental)]
 public abstract class NpgsqlDatabaseInfo
 {
     #region Fields

diff --git a/src/Npgsql/Internal/NpgsqlReadBuffer.cs b/src/Npgsql/Internal/NpgsqlReadBuffer.cs
@@ -2,6 +2,7 @@
 using System.Buffers;
 using System.Buffers.Binary;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Net.Sockets;
 using System.Runtime.CompilerServices;
@@ -17,6 +18,7 @@ namespace Npgsql.Internal;
 /// A buffer used by Npgsql to read data from the socket efficiently.
 /// Provides methods which decode different values types and tracks the current position.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 sealed partial class NpgsqlReadBuffer : IDisposable
 {
     #region Fields and Properties

diff --git a/src/Npgsql/Internal/PgBufferedConverter.cs b/src/Npgsql/Internal/PgBufferedConverter.cs
@@ -5,6 +5,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public abstract class PgBufferedConverter<T> : PgConverter<T>
 {
     protected PgBufferedConverter(bool customDbNullPredicate = false) : base(customDbNullPredicate) { }

diff --git a/src/Npgsql/Internal/PgConverter.cs b/src/Npgsql/Internal/PgConverter.cs
@@ -8,6 +8,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public abstract class PgConverter
 {
     internal DbNullPredicate DbNullPredicateKind { get; }

diff --git a/src/Npgsql/Internal/PgConverterResolver.cs b/src/Npgsql/Internal/PgConverterResolver.cs
@@ -1,8 +1,10 @@
 using System;
+using System.Diagnostics.CodeAnalysis;
 using Npgsql.Internal.Postgres;
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public abstract class PgConverterResolver
 {
     private protected PgConverterResolver() { }

diff --git a/src/Npgsql/Internal/PgReader.cs b/src/Npgsql/Internal/PgReader.cs
@@ -10,6 +10,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public class PgReader
 {
     // We don't want to add a ton of memory pressure for large strings.

diff --git a/src/Npgsql/Internal/PgSerializerOptions.cs b/src/Npgsql/Internal/PgSerializerOptions.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Runtime.CompilerServices;
 using System.Text;
@@ -8,6 +9,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public sealed class PgSerializerOptions
 {
     /// <summary>

diff --git a/src/Npgsql/Internal/PgStreamingConverter.cs b/src/Npgsql/Internal/PgStreamingConverter.cs
@@ -1,11 +1,13 @@
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public abstract class PgStreamingConverter<T> : PgConverter<T>
 {
     protected PgStreamingConverter(bool customDbNullPredicate = false) : base(customDbNullPredicate) { }

diff --git a/src/Npgsql/Internal/PgTypeInfo.cs b/src/Npgsql/Internal/PgTypeInfo.cs
@@ -4,6 +4,7 @@
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public class PgTypeInfo
 {
     readonly bool _canBinaryConvert;

diff --git a/src/Npgsql/Internal/PgTypeInfoResolverFactory.cs b/src/Npgsql/Internal/PgTypeInfoResolverFactory.cs
@@ -1,5 +1,8 @@
+using System.Diagnostics.CodeAnalysis;
+
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public abstract class PgTypeInfoResolverFactory
 {
     public abstract IPgTypeInfoResolver CreateResolver();

diff --git a/src/Npgsql/Internal/PgWriter.cs b/src/Npgsql/Internal/PgWriter.cs
@@ -2,6 +2,7 @@
 using System.Buffers;
 using System.Buffers.Binary;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
@@ -92,6 +93,7 @@ public ValueTask FlushAsync(CancellationToken cancellationToken = default)
         => new(_buffer.Flush(async: true, cancellationToken));
 }
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public sealed class PgWriter
 {
     readonly IBufferWriter<byte> _writer;
@@ -568,6 +570,7 @@ public override long Seek(long offset, SeekOrigin origin)
 }
 
 // No-op for now.
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public struct NestedWriteScope : IDisposable
 {
     public void Dispose()

diff --git a/src/Npgsql/Internal/Postgres/DataTypeName.cs b/src/Npgsql/Internal/Postgres/DataTypeName.cs
@@ -1,11 +1,13 @@
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Npgsql.Internal.Postgres;
 
 /// <summary>
 /// Represents the fully-qualified name of a PostgreSQL type.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 [DebuggerDisplay("{DisplayName,nq}")]
 public readonly struct DataTypeName : IEquatable<DataTypeName>
 {

diff --git a/src/Npgsql/Internal/Postgres/Field.cs b/src/Npgsql/Internal/Postgres/Field.cs
@@ -1,6 +1,9 @@
+using System.Diagnostics.CodeAnalysis;
+
 namespace Npgsql.Internal.Postgres;
 
 /// Base field type shared between tables and composites.
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct Field
 {
     public Field(string name, PgTypeId pgTypeId, int typeModifier)

diff --git a/src/Npgsql/Internal/Postgres/Oid.cs b/src/Npgsql/Internal/Postgres/Oid.cs
@@ -1,7 +1,9 @@
 using System;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Npgsql.Internal.Postgres;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct Oid: IEquatable<Oid>
 {
     public Oid(uint value) => Value = value;

diff --git a/src/Npgsql/Internal/Postgres/PgTypeId.cs b/src/Npgsql/Internal/Postgres/PgTypeId.cs
@@ -6,6 +6,7 @@ namespace Npgsql.Internal.Postgres;
 /// <summary>
 /// A discriminated union of <see cref="Oid" /> and <see cref="DataTypeName" />.
 /// </summary>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct PgTypeId: IEquatable<PgTypeId>
 {
     readonly DataTypeName _dataTypeName;

diff --git a/src/Npgsql/Internal/Size.cs b/src/Npgsql/Internal/Size.cs
@@ -1,15 +1,18 @@
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public enum SizeKind
 {
     Unknown = 0,
     Exact,
     UpperBound
 }
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
 public readonly struct Size : IEquatable<Size>
 {

diff --git a/src/Npgsql/Internal/TypeInfoMapping.cs b/src/Npgsql/Internal/TypeInfoMapping.cs
@@ -19,8 +19,10 @@ namespace Npgsql.Internal;
 /// <param name="resolvedDataTypeName">
 /// Signals whether a resolver based TypeInfo can keep its PgTypeId undecided or whether it should follow mapping.DataTypeName.
 /// </param>
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public delegate PgTypeInfo TypeInfoFactory(PgSerializerOptions options, TypeInfoMapping mapping, bool resolvedDataTypeName);
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public enum MatchRequirement
 {
     /// Match when the clr type and datatype name both match.
@@ -33,6 +35,7 @@ public enum MatchRequirement
 }
 
 /// A factory for well-known PgConverters.
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public static class PgConverterFactory
 {
     public static PgConverter<T[]> CreateArrayMultirangeConverter<T>(PgConverter<T> rangeConverter, PgSerializerOptions options) where T : notnull
@@ -55,6 +58,7 @@ public static PgConverter<TBase> CreatePolymorphicArrayConverter<TBase>(Func<PgC
 }
 
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct TypeInfoMapping
 {
     public TypeInfoMapping(Type type, string dataTypeName, TypeInfoFactory factory)
@@ -99,6 +103,7 @@ string DebuggerDisplay
     }
 }
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public sealed class TypeInfoMappingCollection
 {
     readonly TypeInfoMappingCollection? _baseCollection;
@@ -731,6 +736,7 @@ static void ThrowBoxingNotSupported(bool resolver)
         => throw new InvalidOperationException($"Boxing converters are not supported, manually construct a mapping over a casting converter{(resolver ? " resolver" : "")} instead.");
 }
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public static class TypeInfoMappingHelpers
 {
     internal static bool TryResolveFullyQualifiedName(PgSerializerOptions options, string dataTypeName, out DataTypeName fqDataTypeName)

diff --git a/src/Npgsql/Internal/ValueMetadata.cs b/src/Npgsql/Internal/ValueMetadata.cs
@@ -1,5 +1,8 @@
+using System.Diagnostics.CodeAnalysis;
+
 namespace Npgsql.Internal;
 
+[Experimental(NpgsqlDiagnostics.ConvertersExperimental)]
 public readonly struct ValueMetadata
 {
     public required DataFormat Format { get; init; }

diff --git a/src/Npgsql/Npgsql.csproj b/src/Npgsql/Npgsql.csproj
@@ -8,6 +8,8 @@
     <TargetFrameworks>netstandard2.0;netstandard2.1;net6.0;net7.0;net8.0</TargetFrameworks>
     <TargetFrameworks Condition="'$(DeveloperBuild)' == 'True'">net8.0</TargetFrameworks>
     <NoWarn>$(NoWarn);CA2017</NoWarn>
+    <NoWarn>$(NoWarn);NPG9001</NoWarn> <!-- Converter-related APIs are experimental -->
+    <NoWarn>$(NoWarn);NPG9002</NoWarn> <!-- DatabaseInfo-related APIs are experimental -->
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Npgsql/NpgsqlDiagnostics.cs b/src/Npgsql/NpgsqlDiagnostics.cs
@@ -0,0 +1,7 @@
+namespace Npgsql;
+
+static class NpgsqlDiagnostics
+{
+    public const string ConvertersExperimental = "NPG9001";
+    public const string DatabaseInfoExperimental = "NPG9002";
+}