From 3682b826122ec38dd028c4cd8921201997ce547e Mon Sep 17 00:00:00 2001
From: Trevor Manz <trevor.j.manz@gmail.com>
Date: Mon, 11 Nov 2024 13:45:31 -0500
Subject: [PATCH] Add comments

---
 src/higlass_schema/utils.py | 32 ++++++++++++++++++++++++++------
 uv.lock                     |  2 +-
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/src/higlass_schema/utils.py b/src/higlass_schema/utils.py
index 9217629..e7cb105 100644
--- a/src/higlass_schema/utils.py
+++ b/src/higlass_schema/utils.py
@@ -8,27 +8,47 @@
 
 class _GenerateJsonSchema(GenerateJsonSchema):
     def field_title_should_be_set(self, schema: CoreSchemaOrField) -> bool:
+        """Check if the title should be set for a field.
+
+        Override the default implementation to not set the title for core
+        schemas. Makes the final schema more readable by removing
+        redundant titles. Explicit Field(title=...) can still be used.
+        """
         return_value = super().field_title_should_be_set(schema)
         if return_value and is_core_schema(schema):
             return False
         return return_value
 
     def nullable_schema(self, schema: core_schema.NullableSchema) -> JsonSchemaValue:
-        inner_json_schema = self.generate_inner(schema["schema"])
-        # ignore the nullable
-        return inner_json_schema
+        """Generate a JSON schema for a nullable schema.
+
+        This overrides the default implementation to ignore the nullable
+        and generate a more simple schema. All the Optional[T] fields
+        are converted to T (instead of the
+        default {"anyOf": [{"type": "null"}, {"type": "T"}]}).
+        """
+        return self.generate_inner(schema["schema"])
 
     def default_schema(self, schema: core_schema.WithDefaultSchema) -> JsonSchemaValue:
+        """Generate a JSON schema for a schema with a default value.
+
+        Similar to above, this overrides the default implementation to
+        not explicity set {"default": null} in the schema when the field
+        is Optional[T] = None.
+        """
         if schema.get("default") is None:
             return self.generate_inner(schema["schema"])
         return super().default_schema(schema)
 
-    def union_schema(self, schema: core_schema.UnionSchema) -> JsonSchemaValue:
-        return super().union_schema(schema)
-
     def generate(
         self, schema: core_schema.CoreSchema, mode: JsonSchemaMode = "validation"
     ) -> JsonSchemaValue:
+        """Generate a JSON schema.
+
+        This overrides the default implementation to remove the titles
+        from the definitions. This makes the final schema more readable.
+        """
+
         json_schema = super().generate(schema, mode=mode)
         # clear the titles from the definitions
         for d in json_schema.get("$defs", {}).values():
diff --git a/uv.lock b/uv.lock
index fdd779c..836a967 100644
--- a/uv.lock
+++ b/uv.lock
@@ -87,7 +87,7 @@ wheels = [
 
 [[package]]
 name = "higlass-schema"
-version = "0.1.1.dev5+gcb01091.d20241110"
+version = "0.1.1.dev4+ga14c66a.d20241111"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },