Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

[BUG](codegen) Union entry-point descriptions are dropped — sourced from FieldInfo.description, never the docstring

Đang mở
  • Có gì không ổn?
#596 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

@sethfitz đang làm issue này rồi.

Từ ngày 23/7/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

Summary

A union type-alias entry point renders no description on its generated markdown page, even when it has a docstring. Segment carries a rich description via Segment.__doc__, but the current transportation markdown renders that text zero times -- the # Segment page goes straight from its title to ## Fields.

Root cause

Union descriptions are sourced from FieldInfo.description during type analysis, never from __doc__. capture_union_members (extraction/type_analyzer.py:161) drives analyze_type, whose captured description is "the first FieldInfo.description found during unwrapping." Segment = Annotated[Union[...], Field(discriminator=...)] has exactly one FieldInfo -- the discriminator Field, which carries no description -- so UnionSpec.description resolves to None. The alias's __doc__ (set via Segment.__doc__ = "...") is never consulted.

Contrast with model classes: extract_model reads a class's __doc__ into RecordSpec.description, so a model's docstring renders. Unions have no equivalent path.

The rendering side is not the problem: the union template already emits {% if model.description %}, so a populated UnionSpec.description would render in the right place. The gap is purely sourcing.

Expectation

Give unions the same docstring path models already have -- source the union description from the docstring. The open decision is the sourcing rule / priority:

  • the alias or class docstring (__doc__)
  • FieldInfo.description (the current source -- keep as an override, or drop?)

This is a deliberate output change: it adds a description paragraph to every documented union page.

Relationship to the RootModel migration (#595)

The RootModel migration is the clean enabler. Once a union entry point is a RootModel class rather than an Annotated[...] alias carrying a Segment.__doc__ = assignment, its description lives in a normal class docstring -- a first-class source identical in kind to a model's. Sourcing from an Annotated alias's __doc__ is comparatively fragile.

Because the fix is a deliberate output change, it is deferred out of the byte-identical Segment-as-RootModel spike (the spike keeps UnionSpec.description at None -> None) and tracked here.

Ngôn ngữ chính
Python
Star
220
Fork
22
Merge trung bình
3 ngày 23 giờ
Pull request đã merge (30 ngày)
14

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của OvertureMaps/schema

Tất cả issue của OvertureMaps/schema

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.