Additional comments.

Author: eiriktsarpalis

src/libraries/System.Text.Json/src/System/Text/Json/Schema/JsonSchemaExporter.cs

@@ -78,22 +78,22 @@ private static JsonSchema MapJsonSchemaCore(
 
             if (cacheResult && state.TryPushType(typeInfo, propertyInfo, out string? existingJsonPointer))
             {
-                // Schema for type has already been generated, return a reference to it.
+                // We're generating the schema of a recursive type, return a reference pointing to the outermost schema.
                 return CompleteSchema(ref state, new JsonSchema { Ref = existingJsonPointer });
             }
 
             JsonConverter effectiveConverter = customConverter ?? typeInfo.Converter;
             JsonNumberHandling effectiveNumberHandling = customNumberHandling ?? typeInfo.NumberHandling ?? typeInfo.Options.NumberHandling;
             if (effectiveConverter.GetSchema(effectiveNumberHandling) is { } schema)
             {
+                // A schema has been provided by the converter.
                 return CompleteSchema(ref state, schema);
             }
 
             if (parentPolymorphicType is null && typeInfo.PolymorphismOptions is { DerivedTypes.Count: > 0 } polyOptions)
             {
                 // This is the base type of a polymorphic type hierarchy. The schema for this type
                 // will include an "anyOf" property with the schemas for all derived types.
-
                 string typeDiscriminatorKey = polyOptions.TypeDiscriminatorPropertyName;
                 List<JsonDerivedType> derivedTypes = new(polyOptions.DerivedTypes);
 
@@ -141,7 +141,7 @@ private static JsonSchema MapJsonSchemaCore(
 
                     state.PopSchemaNode();
 
-                    // Determine if all derived types have the same schema type.
+                    // Determine if all derived schemas have the same type.
                     if (anyOf.Count == 0)
                     {
                         schemaType = derivedSchema.Type;
@@ -245,6 +245,9 @@ private static JsonSchema MapJsonSchemaCore(
 
                         (properties ??= []).Add(new(property.Name, propertySchema));
 
+                        // Mark as required if either the property is required or the associated constructor parameter is non-optional.
+                        // While the latter implies the former in cases where the JsonSerializerOptions.RespectRequiredConstructorParameters
+                        // setting has been enabled, for the case of the schema exporter we always mark non-optional constructor parameters as required.
                         if (property is { IsRequired: true } or { AssociatedParameter.IsRequiredParameter: true })
                         {
                             (required ??= []).Add(property.Name);
@@ -340,13 +343,17 @@ private static JsonSchema MapJsonSchemaCore(
 
                 default:
                     Debug.Assert(typeInfo.Kind is JsonTypeInfoKind.None);
+                    // Return a `true` schema for types with user-defined converters.
                     return CompleteSchema(ref state, JsonSchema.True);
             }
 
             JsonSchema CompleteSchema(ref GenerationState state, JsonSchema schema)
             {
                 if (schema.Ref is null)
                 {
+                    // A schema is marked as nullable if either
+                    // 1. We have a schema for a property where either the getter or setter are marked as nullable.
+                    // 2. We have a schema for a reference type, unless we're explicitly treating null-oblivious types as non-nullable.
                     bool isNullableSchema = propertyInfo != null
                         ? propertyInfo.IsGetNullable || propertyInfo.IsSetNullable
                         : typeInfo.CanBeNull && !parentPolymorphicTypeIsNonNullable && !state.ExporterOptions.TreatNullObliviousAsNonNullable;
@@ -364,6 +371,7 @@ JsonSchema CompleteSchema(ref GenerationState state, JsonSchema schema)
 
                 if (state.ExporterOptions.TransformSchemaNode != null)
                 {
+                    // Prime the schema for invocation by the JsonNode transformer.
                     schema.ExporterContext = state.CreateContext(typeInfo, propertyInfo);
                 }