[BUG] API trait summaries omit the implementing type and conversion direction #6

New issue

Closed

opened 2026-09-12 16:58:53 +02:00 by erikinkinen · 0 comments

erikinkinen commented

2026-09-12 16:58:53 +02:00

Owner

Summary

Generated library references list only trait names and arguments, omitting the type that implements each trait. Rustdoc can associate a conversion implementation with both its source and destination types. The current renderer consequently presents an outgoing conversion as though it were implemented by the type whose section is being read, and distinct implementations can collapse into one summary.

Reproduction

At docs fe6f8f7dd8438c4a9e8566ad8293a54edc323d9e, inspect explicit_trait_impls in scripts/generate-library-api-reference.py. It takes each non-synthetic, non-blanket implementation from a public type's Rustdoc impls list, renders only trait, and deduplicates that text. The implementing for type is ignored.

Generate the selected lib-posixabi reference from its original Rustdoc JSON. For example, these distinct conversion directions must retain their implementing type:

impl From<TimespecV1> for RawTimespecV1
impl TryFrom<RawTimespecV1> for TimespecV1

The freshly generated arithmetic reference from lib-posixabi 2ce268816eb6f083348d6d8cf5dc5362e4098071 lists both abbreviated traits under both types. The already published checked/raw identity references have the same problem. No runtime execution is needed to reproduce this rendering defect.

Expected and actual behavior

Expected: a reader can identify the implementing type, conversion direction and applicable generic constraints from each explicit implementation summary. Related implementations must not be mistaken for traits implemented by the section's type. Distinct headers must remain distinct.

Actual: the checked and raw timespec sections both display From<TimespecV1> and TryFrom<RawTimespecV1> without their different implementing types. The source JSON preserves that distinction; the renderer discards it. Successful generation and typesetting do not establish semantic accuracy.

Environment and identity

Renderer: docs fe6f8f7dd8438c4a9e8566ad8293a54edc323d9e.
Published ABI reference source: 79a3b02cacc5e56eb53e2d5adbdc24efdeaa21cd; expanded arithmetic source: 2ce268816eb6f083348d6d8cf5dc5362e4098071.
New arithmetic JSON: public Rustdoc format 54 from explicitly selected Rust 1.90.0-nightly, commit 430d6eddfc6a455ca4a0137c0822a982cccd3b2b.
Host-only documentation generation from explicitly supplied JSON and catalog. No guest or resource authority is introduced by the API values or this renderer.
Last known correct full implementation summary has not been established.

Evidence and prior checks

The original field-level JSON and generated TeX are retained. The new arithmetic inventory has 137 public routes, twenty additions and no removed routes; its generator/check passes, demonstrating that existing freshness checks do not detect this semantic loss. Current Rust implementation and CI pass independently; they do not validate the prose's attribution.

The renderer currently filters synthetic and blanket implementations. The correction must preserve that selection policy unless separately reviewed, retain implementing types and generic constraints, and test checked/raw conversion directions independently. Review the affected retained snapshots against their exact JSON digests before regenerating them; historical source labels must not become fresh-source claims.

The correction is signed and pushed as Docs 3fd9a53548a45967948c0000fa9465c96330ee95 in WIP PR #4. Full implementation headers preserve direction, implementing type, arguments, generic constraints, safety and polarity. Repeated references to one Rustdoc ID are deduplicated; distinct implementation identities remain separate. Colliding source spellings receive defining-type identity comments, explicitly distinguished from public access routes. Enum summaries are a separate documentation expansion.

All 44 warning-denied documentation tests and all 34 selected reference checks pass. Twelve original implementation cases fail against the preceding renderer and pass with the correction. Thirty-two references change and two remain byte-identical; the 33 historical catalog rows/JSON digests stay unchanged, while the compatibility entry selects its 137-route original arithmetic snapshot. The revised complete manual passes in 169.96 seconds: 2,313 pages, 416,124 finite word boxes, no final warnings or out-of-page text, with independent visual checks. PDF SHA-256 is a44c7263ae601584c85ccfe089db48ae1484a1fa3c9000c9db09f124160e7056. Exact-head push CI 817 and PR CI 818 now both pass all jobs, including 44 tests and the complete 2,313-page manual. Provisional cross-reference warnings resolve before the clean final TeX pass and enforced final-log gate. The implementing-type/direction defect is corrected in the selected references; the separate audit of historical JSON provenance remains open and is not claimed by this fix.

Tracking

Documentation stream: docs #1; related declaration-shape defect: docs #5; implementation: docs PR #4; ABI contract: lib-posixabi #1.

Add independent literal fixtures for implementation direction and generic identity, regenerate affected references from verified original inputs, and pass documentation unit/freshness checks plus the complete manual's final warning gate. Do not publish the misleading arithmetic candidate as accepted documentation or alter Rust API behavior to fit the renderer.

## Summary Generated library references list only trait names and arguments, omitting the type that implements each trait. Rustdoc can associate a conversion implementation with both its source and destination types. The current renderer consequently presents an outgoing conversion as though it were implemented by the type whose section is being read, and distinct implementations can collapse into one summary. ## Reproduction At docs `fe6f8f7dd8438c4a9e8566ad8293a54edc323d9e`, inspect `explicit_trait_impls` in `scripts/generate-library-api-reference.py`. It takes each non-synthetic, non-blanket implementation from a public type's Rustdoc `impls` list, renders only `trait`, and deduplicates that text. The implementing `for` type is ignored. Generate the selected lib-posixabi reference from its original Rustdoc JSON. For example, these distinct conversion directions must retain their implementing type: ```rust impl From<TimespecV1> for RawTimespecV1 impl TryFrom<RawTimespecV1> for TimespecV1 ``` The freshly generated arithmetic reference from lib-posixabi `2ce268816eb6f083348d6d8cf5dc5362e4098071` lists both abbreviated traits under both types. The already published checked/raw identity references have the same problem. No runtime execution is needed to reproduce this rendering defect. ## Expected and actual behavior Expected: a reader can identify the implementing type, conversion direction and applicable generic constraints from each explicit implementation summary. Related implementations must not be mistaken for traits implemented by the section's type. Distinct headers must remain distinct. Actual: the checked and raw timespec sections both display `From<TimespecV1>` and `TryFrom<RawTimespecV1>` without their different implementing types. The source JSON preserves that distinction; the renderer discards it. Successful generation and typesetting do not establish semantic accuracy. ## Environment and identity - Renderer: docs `fe6f8f7dd8438c4a9e8566ad8293a54edc323d9e`. - Published ABI reference source: `79a3b02cacc5e56eb53e2d5adbdc24efdeaa21cd`; expanded arithmetic source: `2ce268816eb6f083348d6d8cf5dc5362e4098071`. - New arithmetic JSON: public Rustdoc format 54 from explicitly selected Rust 1.90.0-nightly, commit `430d6eddfc6a455ca4a0137c0822a982cccd3b2b`. - Host-only documentation generation from explicitly supplied JSON and catalog. No guest or resource authority is introduced by the API values or this renderer. - Last known correct full implementation summary has not been established. ## Evidence and prior checks The original field-level JSON and generated TeX are retained. The new arithmetic inventory has 137 public routes, twenty additions and no removed routes; its generator/check passes, demonstrating that existing freshness checks do not detect this semantic loss. Current Rust implementation and CI pass independently; they do not validate the prose's attribution. The renderer currently filters synthetic and blanket implementations. The correction must preserve that selection policy unless separately reviewed, retain implementing types and generic constraints, and test checked/raw conversion directions independently. Review the affected retained snapshots against their exact JSON digests before regenerating them; historical source labels must not become fresh-source claims. The correction is signed and pushed as Docs `3fd9a53548a45967948c0000fa9465c96330ee95` in [WIP PR #4](https://git.erikinkinen.fi/erix/docs/pulls/4). Full implementation headers preserve direction, implementing type, arguments, generic constraints, safety and polarity. Repeated references to one Rustdoc ID are deduplicated; distinct implementation identities remain separate. Colliding source spellings receive defining-type identity comments, explicitly distinguished from public access routes. Enum summaries are a separate documentation expansion. All 44 warning-denied documentation tests and all 34 selected reference checks pass. Twelve original implementation cases fail against the preceding renderer and pass with the correction. Thirty-two references change and two remain byte-identical; the 33 historical catalog rows/JSON digests stay unchanged, while the compatibility entry selects its 137-route original arithmetic snapshot. The revised complete manual passes in 169.96 seconds: 2,313 pages, 416,124 finite word boxes, no final warnings or out-of-page text, with independent visual checks. PDF SHA-256 is `a44c7263ae601584c85ccfe089db48ae1484a1fa3c9000c9db09f124160e7056`. Exact-head [push CI 817](https://git.erikinkinen.fi/erix/docs/actions/runs/817) and [PR CI 818](https://git.erikinkinen.fi/erix/docs/actions/runs/818) now both pass all jobs, including 44 tests and the complete 2,313-page manual. Provisional cross-reference warnings resolve before the clean final TeX pass and enforced final-log gate. The implementing-type/direction defect is corrected in the selected references; the separate audit of historical JSON provenance remains open and is not claimed by this fix. ## Tracking Documentation stream: [docs #1](https://git.erikinkinen.fi/erix/docs/issues/1); related declaration-shape defect: [docs #5](https://git.erikinkinen.fi/erix/docs/issues/5); implementation: [docs PR #4](https://git.erikinkinen.fi/erix/docs/pulls/4); ABI contract: [lib-posixabi #1](https://git.erikinkinen.fi/erix/lib-posixabi/issues/1). Add independent literal fixtures for implementation direction and generic identity, regenerate affected references from verified original inputs, and pass documentation unit/freshness checks plus the complete manual's final warning gate. Do not publish the misleading arithmetic candidate as accepted documentation or alter Rust API behavior to fit the renderer.

erikinkinen added the

phase-6

bug

docs

labels

2026-09-12 16:58:53 +02:00

~~erikinkinen referenced this issue from erix/lib-posixabi 2026-09-12 16:59:59 +02:00~~

WIP: Define compatibility ABI values and checked numeric ranges #3

~~erikinkinen referenced this issue 2026-09-12 18:19:44 +02:00~~

WIP: Document native authority and verify workspace and command evidence #4

erikinkinen closed this issue

2026-09-12 18:32:07 +02:00