Add comments

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():