[BUG](codegen) Union entry-point descriptions are dropped — sourced from FieldInfo.description, never the docstring
メンテナーはふだん 1 日以内に返信
@sethfitz がすでに取り組んでいます。
2026年7月23日 から。
評価
この issue はまだ評価されていません。
説明
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.
- 主要言語
- Python
- スター
- 220
- フォーク
- 22
- 平均マージ
- 3日 13時間
- マージ済み PR（30日）
- 16
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
OvertureMaps/schema のほかの issue
-
[BUG] `put_required` and its siblings raise a `TypeError` with unformatted placeholders対応中かも @sethfitz が 4 日前に担当しました。 オープン
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
OvertureMaps/schema#790 ·
メンテナーはふだん 1 日以内に返信
-
[BUG](cli) `validate` reports empty input as a data error対応中かも @sethfitz が 4 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
OvertureMaps/schema#788 ·
メンテナーはふだん 1 日以内に返信
-
[DOCS] `make check` reports "no tests ran" without saying why対応中かも @sethfitz が 18 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 90/100
OvertureMaps/schema#771 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
OvertureMaps/schema#694 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
OvertureMaps/schema#693 ·
メンテナーはふだん 1 日以内に返信
OvertureMaps/schema の issue をすべて見る
似ている issue
-
Project submission:オープン
難易度 1/5 1時間未満 初心者へのやさしさ 72/100
slavakurilyak/awesome-ai-agents#845 ·
メンテナーはふだん 1 日以内に返信
-
tests: pin that the atomic writers in utils/paths.py stage the temporary file in the target's directory対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープンdifficulty:2 enhancement good first issue
難易度 1/5 1〜3時間 初心者へのやさしさ 92/100
MakazhanAlpamys/Soup#2178 ·
メンテナーはふだん 1 日以内に返信
-
[BUG] dcg.waggr permutation p-values are folded twice, so near-zero scores get the smallest p-valuesオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
scverse/rapids-singlecell#854 ·
メンテナーはふだん 1 日以内に返信
-
Slang input: int8_t4_packed and uint8_t4_packed are copied into CrossGL対応中かも @ninglinLiu が今日担当しました。 オープンarea:frontend backend:slang bug direction:input
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
メンテナーはふだん 1 日以内に返信
-
random_elements(unique=True) on an OrderedDict: ZeroDivisionError once only zero weights remain, AssertionError with use_weighting=False対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 85/100
メンテナーはふだん 13 日以内に返信