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
This commit is contained in:
LGUG2Z committed 2025-12-27 22:21:46 -08:00
1 parent 91463ff033
commit 12556acc36
2 files changed
+42 -36

No files matched your search

+28
View File
@@ -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)
+14 -36
View File
@@ -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 -%}