Rename "PolicyProperty" to "PropertyInfoForClassInfo" and update null…

…ability (dotnet#33432)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/DictionaryDefaultConverter.cs

@@ -33,7 +33,7 @@ protected virtual void CreateCollection(ref ReadStack state) { }
 
         protected static JsonConverter<TValue> GetElementConverter(ref ReadStack state)
         {
-            JsonConverter<TValue> converter = (JsonConverter<TValue>)state.Current.JsonClassInfo.ElementClassInfo!.PolicyProperty!.ConverterBase;
+            JsonConverter<TValue> converter = (JsonConverter<TValue>)state.Current.JsonClassInfo.ElementClassInfo!.PropertyInfoForClassInfo.ConverterBase;
             Debug.Assert(converter != null); // It should not be possible to have a null converter at this point.
 
             return converter;
@@ -289,7 +289,7 @@ internal sealed override bool OnTryWrite(
                     }
                 }
 
-                state.Current.DeclaredJsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PolicyProperty!;
+                state.Current.DeclaredJsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PropertyInfoForClassInfo;
             }
 
             bool success = OnWriteResume(writer, dictionary, options, ref state);

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IEnumerableDefaultConverter.cs

@@ -19,7 +19,7 @@ protected virtual void ConvertCollection(ref ReadStack state, JsonSerializerOpti
 
         protected static JsonConverter<TElement> GetElementConverter(ref ReadStack state)
         {
-            JsonConverter<TElement> converter = (JsonConverter<TElement>)state.Current.JsonClassInfo.ElementClassInfo!.PolicyProperty!.ConverterBase;
+            JsonConverter<TElement> converter = (JsonConverter<TElement>)state.Current.JsonClassInfo.ElementClassInfo!.PropertyInfoForClassInfo.ConverterBase;
             Debug.Assert(converter != null); // It should not be possible to have a null converter at this point.
 
             return converter;
@@ -143,7 +143,7 @@ internal override bool OnTryRead(
                         }
                     }
 
-                    state.Current.JsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PolicyProperty!;
+                    state.Current.JsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PropertyInfoForClassInfo;
                     state.Current.ObjectState = StackFrameObjectState.CreatedObject;
                 }
 
@@ -268,7 +268,7 @@ internal sealed override bool OnTryWrite(Utf8JsonWriter writer, TCollection valu
                         state.Current.MetadataPropertyName = metadata;
                     }
 
-                    state.Current.DeclaredJsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PolicyProperty!;
+                    state.Current.DeclaredJsonPropertyInfo = state.Current.JsonClassInfo.ElementClassInfo!.PropertyInfoForClassInfo;
                 }
 
                 success = OnWriteResume(writer, value, options, ref state);

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonClassInfo.AddProperty.cs

@@ -58,11 +58,9 @@ internal static JsonPropertyInfo CreateProperty(
 
         /// <summary>
         /// Create a <see cref="JsonPropertyInfo"/> for a given Type.
-        /// A policy property is not a real property on a type; instead it leverages the existing converter
-        /// logic and generic support to avoid boxing. It is used with values types, elements from collections and
-        /// dictionaries, and collections themselves. Typically it would represent a CLR type such as System.String.
+        /// See <seealso cref="JsonClassInfo.PropertyInfoForClassInfo"/>.
         /// </summary>
-        internal static JsonPropertyInfo CreatePolicyProperty(
+        internal static JsonPropertyInfo CreatePropertyInfoForClassInfo(
             Type declaredPropertyType,
             Type runtimePropertyType,
             JsonConverter converter,

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonClassInfo.cs

@@ -122,7 +122,7 @@ public JsonClassInfo(Type type, JsonSerializerOptions options)
                 Options);
 
             ClassType = converter.ClassType;
-            PolicyProperty = CreatePolicyProperty(Type, runtimeType, converter, Options);
+            PropertyInfoForClassInfo = CreatePropertyInfoForClassInfo(Type, runtimeType, converter, Options);
 
             switch (ClassType)
             {
@@ -391,7 +391,23 @@ private Dictionary<string, JsonPropertyInfo> CreatePropertyCache(int capacity)
             return new Dictionary<string, JsonPropertyInfo>(capacity, comparer);
         }
 
-        public JsonPropertyInfo? PolicyProperty { get; private set; }
+        /// <summary>
+        /// The JsonPropertyInfo for this JsonClassInfo. It is used to obtain the converter for the ClassInfo.
+        /// </summary>
+        /// <remarks>
+        /// The returned JsonPropertyInfo does not represent a real property; instead it represents either:
+        /// a collection element type,
+        /// a generic type parameter,
+        /// a property type (if pushed to a new stack frame),
+        /// or the root type passed into the root serialization APIs.
+        /// For example, for a property returning <see cref="Collections.Generic.List{T}"/> where T is a string,
+        /// a JsonClassInfo will be created with .Type=typeof(string) and .PropertyInfoForClassInfo=JsonPropertyInfo{string}.
+        /// Without this property, a "Converter" property would need to be added to JsonClassInfo and there would be several more
+        /// `if` statements to obtain the converter from either the actual JsonPropertyInfo (for a real property) or from the
+        /// ClassInfo (for the cases mentioned above). In addition, methods that have a JsonPropertyInfo argument would also likely
+        /// need to add an argument for JsonClassInfo.
+        /// </remarks>
+        public JsonPropertyInfo PropertyInfoForClassInfo { get; private set; }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         private static bool TryIsPropertyRefEqual(in PropertyRef propertyRef, ReadOnlySpan<byte> propertyName, ulong key, [NotNullWhen(true)] ref JsonPropertyInfo? info)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonConverterOfT.ReadCore.cs

@@ -57,7 +57,7 @@ internal T ReadCore(
                     }
                 }
 
-                JsonPropertyInfo jsonPropertyInfo = state.Current.JsonClassInfo.PolicyProperty!;
+                JsonPropertyInfo jsonPropertyInfo = state.Current.JsonClassInfo.PropertyInfoForClassInfo;
                 bool success = TryRead(ref reader, jsonPropertyInfo.RuntimePropertyType!, options, ref state, out T value);
                 if (success)
                 {

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonPropertyInfo.cs

@@ -195,7 +195,7 @@ public bool ReadJsonAndAddExtensionProperty(object obj, ref ReadStack state, ref
                 else
                 {
                     JsonConverter<object> converter = (JsonConverter<object>)
-                        state.Current.JsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PolicyProperty!.ConverterBase;
+                        state.Current.JsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PropertyInfoForClassInfo.ConverterBase;
 
                     if (!converter.TryRead(ref reader, typeof(JsonElement), Options, ref state, out object? value))
                     {
@@ -213,7 +213,7 @@ public bool ReadJsonAndAddExtensionProperty(object obj, ref ReadStack state, ref
                 IDictionary<string, JsonElement> dictionaryJsonElement = (IDictionary<string, JsonElement>)propValue;
 
                 JsonConverter<JsonElement> converter = (JsonConverter<JsonElement>)
-                    state.Current.JsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PolicyProperty!.ConverterBase;
+                    state.Current.JsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PropertyInfoForClassInfo.ConverterBase;
 
                 if (!converter.TryRead(ref reader, typeof(JsonElement), Options, ref state, out JsonElement value))
                 {

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonPropertyInfoOfTTypeToConvert.cs

@@ -124,7 +124,7 @@ public override bool GetMemberAndWriteJsonExtensionData(object obj, ref WriteSta
             }
             else
             {
-                state.Current.PolymorphicJsonPropertyInfo = state.Current.DeclaredJsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PolicyProperty;
+                state.Current.PolymorphicJsonPropertyInfo = state.Current.DeclaredJsonPropertyInfo!.RuntimeClassInfo.ElementClassInfo!.PropertyInfoForClassInfo;
                 success = Converter.TryWriteDataExtensionProperty(writer, value, Options, ref state);
             }
 

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Helpers.cs

@@ -21,7 +21,7 @@ private static void WriteCore<TValue>(Utf8JsonWriter writer, TValue value, Type
 
             WriteStack state = default;
             state.Initialize(inputType, options, supportContinuation: false);
-            JsonConverter jsonConverter = state.Current.JsonClassInfo!.PolicyProperty!.ConverterBase;
+            JsonConverter jsonConverter = state.Current.JsonClassInfo!.PropertyInfoForClassInfo.ConverterBase;
 
             bool success = WriteCore(jsonConverter, writer, value, options, ref state);
             Debug.Assert(success);

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializer.Write.Stream.cs

@@ -94,7 +94,7 @@ private static async Task WriteAsyncCore<TValue>(Stream utf8Json, TValue value,
                 WriteStack state = default;
                 state.Initialize(inputType, options, supportContinuation: true);
 
-                JsonConverter converterBase = state.Current.JsonClassInfo!.PolicyProperty!.ConverterBase;
+                JsonConverter converterBase = state.Current.JsonClassInfo!.PropertyInfoForClassInfo.ConverterBase;
 
                 bool isFinalBlock;
 

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/ReadStack.cs

@@ -78,7 +78,7 @@ public void Initialize(Type type, JsonSerializerOptions options, bool supportCon
             Current.JsonClassInfo = jsonClassInfo;
 
             // The initial JsonPropertyInfo will be used to obtain the converter.
-            Current.JsonPropertyInfo = jsonClassInfo.PolicyProperty;
+            Current.JsonPropertyInfo = jsonClassInfo.PropertyInfoForClassInfo;
 
             if (options.ReferenceHandling.ShouldReadPreservedReferences())
             {
@@ -114,7 +114,7 @@ public void Push()
                     Current.Reset();
 
                     Current.JsonClassInfo = jsonClassInfo;
-                    Current.JsonPropertyInfo = jsonClassInfo.PolicyProperty;
+                    Current.JsonPropertyInfo = jsonClassInfo.PropertyInfoForClassInfo;
                 }
             }
             else if (_continuationCount == 1)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/ReadStackFrame.cs

@@ -61,7 +61,7 @@ public void InitializeReEntry(Type type, JsonSerializerOptions options, string?
             JsonClassInfo jsonClassInfo = options.GetOrAddClass(type);
 
             // The initial JsonPropertyInfo will be used to obtain the converter.
-            JsonPropertyInfo = jsonClassInfo.PolicyProperty;
+            JsonPropertyInfo = jsonClassInfo.PropertyInfoForClassInfo;
 
             // Set for exception handling calculation of JsonPath.
             JsonPropertyNameAsString = propertyName;

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/WriteStack.cs

@@ -74,7 +74,7 @@ public void Initialize(Type type, JsonSerializerOptions options, bool supportCon
 
             if ((jsonClassInfo.ClassType & (ClassType.Enumerable | ClassType.Dictionary)) == 0)
             {
-                Current.DeclaredJsonPropertyInfo = jsonClassInfo.PolicyProperty;
+                Current.DeclaredJsonPropertyInfo = jsonClassInfo.PropertyInfoForClassInfo;
             }
 
             if (options.ReferenceHandling.ShouldWritePreservedReferences())
@@ -102,7 +102,7 @@ public void Push()
                     Current.Reset();
 
                     Current.JsonClassInfo = jsonClassInfo;
-                    Current.DeclaredJsonPropertyInfo = jsonClassInfo.PolicyProperty;
+                    Current.DeclaredJsonPropertyInfo = jsonClassInfo.PropertyInfoForClassInfo;
                 }
             }
             else if (_continuationCount == 1)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/WriteStackFrame.cs

@@ -20,8 +20,8 @@ internal struct WriteStackFrame
         /// The original JsonPropertyInfo that is not changed. It contains all properties.
         /// </summary>
         /// <remarks>
-        /// For objects, it is either the policy property for the class or the current property.
-        /// For collections, it is either the policy property for the class or the policy property for the current element.
+        /// For objects, it is either the actual (real) JsonPropertyInfo or the <see cref="JsonClassInfo.PropertyInfoForClassInfo"/> for the class.
+        /// For collections, it is the <see cref="JsonClassInfo.PropertyInfoForClassInfo"/> for the class and current element.
         /// </remarks>
         public JsonPropertyInfo? DeclaredJsonPropertyInfo;
 
@@ -64,8 +64,8 @@ internal struct WriteStackFrame
         /// The run-time JsonPropertyInfo that contains the ClassInfo and ConverterBase for polymorphic scenarios.
         /// </summary>
         /// <remarks>
-        /// For objects, it is either the policy property for the class or the policy property for the current property.
-        /// For collections, it is either the policy property for the class or the policy property for the current element.
+        /// For objects, it is the <see cref="JsonClassInfo.PropertyInfoForClassInfo"/> for the class and current property.
+        /// For collections, it is the <see cref="JsonClassInfo.PropertyInfoForClassInfo"/> for the class and current element.
         /// </remarks>
         public JsonPropertyInfo? PolymorphicJsonPropertyInfo;
 
@@ -104,7 +104,7 @@ public JsonConverter InitializeReEntry(Type type, JsonSerializerOptions options,
             // Set for exception handling calculation of JsonPath.
             JsonPropertyNameAsString = propertyName;
 
-            PolymorphicJsonPropertyInfo = newClassInfo.PolicyProperty!;
+            PolymorphicJsonPropertyInfo = newClassInfo.PropertyInfoForClassInfo;
             return PolymorphicJsonPropertyInfo.ConverterBase;
         }