more clear comments + separate options

django_setup_configuration/documentation/model_directive.py

@@ -73,21 +73,27 @@ def insert_example_with_comments(
     example_data[field_name] = example
     if field_info.description:
         yaml_set_comment_with_max_length(
-            example_data, field_name, field_info.description, 80, indent=depth * 2
+            example_data,
+            field_name,
+            f"DESCRIPTION: {field_info.description}",
+            80,
+            indent=depth * 2,
         )
 
     if default := get_default_from_field_info(field_info):
         example_data.yaml_set_comment_before_after_key(
-            field_name, f"default value: {default}", indent=depth * 2
+            field_name, f"DEFAULT VALUE: {default}", indent=depth * 2
         )
 
     if get_origin(field_info.annotation) == Literal:
         example_data.yaml_set_comment_before_after_key(
-            field_name, f"possible values: {get_args(field_info.annotation)}", indent=depth * 2
+            field_name,
+            f"POSSIBLE VALUES: {get_args(field_info.annotation)}",
+            indent=depth * 2,
         )
 
     example_data.yaml_set_comment_before_after_key(
-        field_name, f"required: {field_info.is_required()}", indent=depth * 2
+        field_name, f"REQUIRED: {field_info.is_required()}", indent=depth * 2
     )
 
 
@@ -102,7 +108,7 @@ def insert_as_full_comment(
     yaml_example = output.getvalue()
     example_data.yaml_set_comment_before_after_key(
         field_name,
-        after=f"{yaml_example}--------------------------\n",
+        after=f"{yaml_example}\n",
         indent=depth * 2,
     )
 
@@ -115,6 +121,7 @@ def generate_model_example(model: Type[BaseModel], depth: int = 0) -> Dict[str,
         _data = process_field_type(
             field_info.annotation, field_info, field_name, depth + 1
         )
+        # TODO refactor this
         if isinstance(_data, PolymorphicExample):
             example = _data.example
         else:
@@ -130,14 +137,23 @@ def generate_model_example(model: Type[BaseModel], depth: int = 0) -> Dict[str,
                 after=(
                     "This value is polymorphic, the possible values are divided by "
                     "dashes and only one of them can be commented out.\n"
-                    "--------------------------"
                 ),
                 indent=depth * 2,
             )
-            for commented_example in _data.commented_out_examples:
+            for i, commented_example in enumerate(_data.commented_out_examples):
+                example_data.yaml_set_comment_before_after_key(
+                    field_name,
+                    after=(f"-------------OPTION {i+1}-------------"),
+                    indent=depth * 2,
+                )
                 insert_as_full_comment(
                     example_data, field_name, commented_example, depth
                 )
+            example_data.yaml_set_comment_before_after_key(
+                field_name,
+                after=(f"-------------OPTION {i+2}-------------"),
+                indent=depth * 2,
+            )
     return example_data
 
 
@@ -173,7 +189,6 @@ def process_field_type(
         ]
         return PolymorphicExample(example=data, commented_out_examples=other)
 
-
     # Handle lists
     if get_origin(field_type) == list:
         list_type = get_args(field_type)[0]