diff --git a/src/FSharp.Data.DesignTime/Json/JsonConversionsGenerator.fs b/src/FSharp.Data.DesignTime/Json/JsonConversionsGenerator.fs
index 289405e63..f0aac56d1 100644
--- a/src/FSharp.Data.DesignTime/Json/JsonConversionsGenerator.fs
+++ b/src/FSharp.Data.DesignTime/Json/JsonConversionsGenerator.fs
@@ -100,15 +100,19 @@ let internal convertJsonValue
                     (<@ (%varExpr).Path() @>, convert <@ Some (%varExpr).JsonValue @>, <@ Some (%varExpr).JsonValue @>))
         | TypeWrapper.Option, true -> convert <@ (%%value: JsonValue option) @>
         | TypeWrapper.Option, false ->
-            //TODO: not covered in tests
+            // Reached when canPassAllConversionCallingTypes=false (e.g. for array element types or
+            // heterogeneous type variants). The caller passes an IJsonDocument; we extract its
+            // JsonValue and wrap it in Some before handing it to the conversion quotation.
             convert <@ Some (%%value: IJsonDocument).JsonValue @>
         | TypeWrapper.Nullable, true ->
-            //TODO: not covered in tests
+            // TypeWrapper.Nullable is never produced by JSON inference (which only emits None or Option).
+            // This branch exists for structural completeness and potential future extensibility.
             typeof<TextRuntime>?(nameof (TextRuntime.OptionToNullable))
                 (field.RuntimeType)
                 (convert <@ (%%value: JsonValue option) @>)
         | TypeWrapper.Nullable, false ->
-            //TODO: not covered in tests
+            // TypeWrapper.Nullable is never produced by JSON inference (which only emits None or Option).
+            // This branch exists for structural completeness and potential future extensibility.
             typeof<TextRuntime>?(nameof (TextRuntime.OptionToNullable))
                 (field.RuntimeType)
                 (convert <@ Some (%%value: IJsonDocument).JsonValue @>)
diff --git a/src/FSharp.Data.DesignTime/Json/JsonGenerator.fs b/src/FSharp.Data.DesignTime/Json/JsonGenerator.fs
index 19218c3a5..ea525b95e 100644
--- a/src/FSharp.Data.DesignTime/Json/JsonGenerator.fs
+++ b/src/FSharp.Data.DesignTime/Json/JsonGenerator.fs
@@ -632,7 +632,12 @@ module JsonTypeBuilder =
 
                                       match propResult.OptionalConverter with
                                       | Some _ ->
-                                          //TODO: not covered in tests
+                                          // Reached when a property is optional (IsOptional=true) but its
+                                          // ConversionCallingType is JsonDocument (optionalityHandledByProperty=false),
+                                          // meaning the property type has a converter but optionality is not handled
+                                          // by the conversion calling type alone. In practice this requires an
+                                          // InferedType.Json(optional=true) property, which the JSON provider does
+                                          // not currently produce.
                                           ctx.JsonRuntimeType?(nameof (JsonRuntime.ConvertOptionalProperty))
                                               (propResult.ConvertedTypeErased ctx)
                                               (jDoc, propName, propResult.ConverterFunc ctx)