From 12556acc36034e7fb2ddb33b15e942d84357bd77 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 27 Dec 2025 22:21:46 -0800 Subject: [PATCH] fix(docgen): prioritize $ref over type in enum variant Value display For Pattern 6 (Internally Tagged + Flatten) enum variants that have both `type: "object"` and `$ref` at the same level, the Value line now shows a link to the referenced type instead of displaying "object". Before: #### Catppuccin Theme from catppuccin-egui **Value:** `object` #### name ...all properties from KomorebiThemeCatppuccin inlined... After: #### Catppuccin Theme from catppuccin-egui **Value:** [`KomorebiThemeCatppuccin`](#komorebithemecatppuccin) Changes: - Move $ref check to top of render_type_badge macro, prioritizing it over type when both are present - Remove property inlining for Pattern 6 variants with $ref since the link makes inlined properties redundant - Add test assertions verifying $ref link display and no property inlining for Pattern 6 variants --- src/mdx_generator.rs | 28 +++++++++++++++++++++ src/templates/mdx_macros.md | 50 +++++++++++-------------------------- 2 files changed, 42 insertions(+), 36 deletions(-) diff --git a/src/mdx_generator.rs b/src/mdx_generator.rs index ba4cde28..e71c4525 100644 --- a/src/mdx_generator.rs +++ b/src/mdx_generator.rs @@ -1371,6 +1371,34 @@ mod tests { total_value_lines, mdx ); + + // Pattern 6 variants with $ref should show the type link, not "object" + // The "Bar" variant has a $ref, so it should show the link + assert!( + mdx.contains("[`GroupingConfig`](#groupingconfig)"), + "Pattern 6 variant with $ref should show type link. MDX:\n{}", + mdx + ); + // The "Bar" variant should NOT show "object" - it should show the $ref link + // Note: "None" variant has no $ref, so it correctly shows "object" + assert!( + !mdx.contains("**Value:** [`GroupingConfig`](#groupingconfig)") + || count_occurrences(&mdx, "**Value:** `object`") <= 1, + "Pattern 6 variant with $ref should show type link instead of 'object'. MDX:\n{}", + mdx + ); + + // Pattern 6 variants with $ref should NOT inline the referenced type's properties + // Since we show a link to the type, the properties are redundant + // The "style" property from GroupingConfig should NOT appear in the variant body + // (it should only appear in the type definition section, not in the enum variant) + let style_count = count_occurrences(&mdx, "#### style"); + assert!( + style_count <= 1, + "Pattern 6 variant should not inline $ref properties. Found {} '#### style' occurrences (should be 0 or 1 for the $defs section only). MDX:\n{}", + style_count, + mdx + ); } // Pattern 7: Externally Tagged Enum (Newtype Variants Only) diff --git a/src/templates/mdx_macros.md b/src/templates/mdx_macros.md index 01efab00..c994465a 100644 --- a/src/templates/mdx_macros.md +++ b/src/templates/mdx_macros.md @@ -20,10 +20,20 @@ {# SECTION 1: Type Badge Rendering #} {# ============================================================================ #} {# Render the type badge for a schema - outputs inline code or links #} -{# Pattern 6: When node has BOTH type AND $ref (flattened config), prioritize type #} +{# When node has $ref, always prioritize it over type (Pattern 6, etc.) #} {% macro render_type_badge(node) %} -{%- if node.type -%} +{%- if node["$ref"] -%} + {# $ref always takes priority - render as link to type definition #} + {%- set ref_name = node["$ref"] | replace(from="#/$defs/", to="") -%} + {%- set display = display_names[ref_name] | default(value=ref_name) -%} + {%- if schema["$defs"][ref_name] -%} + {%- set ref_def = schema["$defs"][ref_name] -%} +[`{{ display }}`](#{{ ref_name | lower }}){% if ref_def._wrapper_inner %} {{ self::render_type_badge(node=ref_def._wrapper_inner) }}{% endif -%} + {%- else -%} +`$ref` + {%- endif -%} +{%- elif node.type -%} {%- if node.type is string -%} {%- if node.type == "array" and node.prefixItems -%} {# Check if all prefixItems have the same type (homogeneous tuple) #} @@ -116,16 +126,6 @@ {%- endif -%} {%- elif node.allOf -%} `allOf` -{%- elif node["$ref"] -%} - {# Reference type (no inline type field) #} - {%- set ref_name = node["$ref"] | replace(from="#/$defs/", to="") -%} - {%- set display = display_names[ref_name] | default(value=ref_name) -%} - {%- if schema["$defs"][ref_name] -%} - {%- set ref_def = schema["$defs"][ref_name] -%} -[`{{ display }}`](#{{ ref_name | lower }}){% if ref_def._wrapper_inner %} {{ self::render_type_badge(node=ref_def._wrapper_inner) }}{% endif -%} - {%- else -%} -`$ref` - {%- endif -%} {%- elif node.const -%} `const` {%- elif node.enum -%} @@ -507,30 +507,8 @@ {% endif -%} {%- endfor -%} {%- endif -%} -{# Pattern 6: If node has both properties AND $ref, also render the referenced type's properties #} -{%- if node["$ref"] -%} - {%- set ref_name = node["$ref"] | replace(from="#/$defs/", to="") -%} - {%- if schema["$defs"][ref_name] -%} - {%- set ref_def = schema["$defs"][ref_name] -%} - {%- if ref_def.properties -%} - {%- set ref_required_arr = ref_def.required | default(value=[]) -%} -{# First render required properties from referenced type #} -{% for prop_name, prop in ref_def.properties -%} -{%- if prop_name in ref_required_arr -%} -{%- set is_required = true -%} -{{ self::render_nested_property(name=prop_name, node=prop, required=is_required, depth=depth + 1, path=path ~ "." ~ prop_name) }} -{% endif -%} -{%- endfor -%} -{# Then render optional properties from referenced type #} -{% for prop_name, prop in ref_def.properties -%} -{%- if prop_name not in ref_required_arr -%} -{%- set is_required = false -%} -{{ self::render_nested_property(name=prop_name, node=prop, required=is_required, depth=depth + 1, path=path ~ "." ~ prop_name) }} -{% endif -%} -{%- endfor -%} - {%- endif -%} - {%- endif -%} -{%- endif -%} +{# Pattern 6: When node has both properties AND $ref, the $ref is shown as a link in Value: #} +{# so we don't need to inline the referenced type's properties here #} {%- elif node["$ref"] -%} {# Reference only, already shown as type badge #} {%- elif node.patternProperties -%}