Skip to content

Conversation

@dtolnay
Copy link
Member

@dtolnay dtolnay commented Sep 25, 2025

#2608 regressed the rustdoc rendered documentation of serde in many ways because rustdoc does not currently handle documentation of cross-crate re-exported items well. For example there is not enough information in the rmeta of dependencies to accurately reconstruct the way that trait associated types are named in signatures. The A-cross-crate-reexports label in rust-lang/rust records numerous other issues.

Before #2608:

After #2608:

This PR works around the cross-crate re-export issues by inlining the items defined by serde_core into serde when building documentation for docs.rs.

@oli-obk
Copy link
Member

oli-obk commented Sep 25, 2025

oof. Very hacky. I'd prefer to just keep the status quo. It's not that bad and we can use it to prioritize the rustdoc issues more

@dtolnay
Copy link
Member Author

dtolnay commented Sep 25, 2025

I would be grateful if you could expedite some fixes in rustdoc, but in my opinion having a workaround in place until rustdoc gets fixed is less bad than having the documentation remain in the current state for the same duration.

The workaround can be removed as soon as the version of nightly rustdoc used by docs.rs no longer produces less legible / less copy-pasteable documentation without it.

Beyond the associated type issue from the screenshots which is my prevailing concern, here are some other issues you could help with, which I have noticed in the serde documentation with re-exports:

  • The use of core::fmt::Result vs core::result::Result<(), core::fmt::Error> in the documentation of impl<'a> Serializer for &mut Formatter<'a>
    • Something else I noticed in this impl, the associated type problem means rustdoc is producing signatures that wouldn't even compile. -> Result<<&mut Formatter<'a> as Serializer>::SerializeSeq, Error>
      error[E0106]: missing lifetime specifier
         --> serde_core/src/ser/fmt.rs:117:60
          |
      117 |     fn serialize_seq(self, _len: Option<usize>) -> Result<<&mut Formatter<'a> as Serializer>::SerializeSeq, fmt::Error> {
          |                                                            ^ expected named lifetime parameter
          |
          = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from

Some other things that are solved by the workaround in this PR, which are not going to be solved in rustdoc and we will need some other workaround (probably easy) if not using this one:

  • Tuple impls, which are rendered impl<'de, T> Deserialize<'de> for (T₁, T₂, …, Tₙ) in serde_core but not serde

  • doc(cfg), such as on serde_core::de::Visitor::visit_string, is missing in serde

@dtolnay dtolnay merged commit 7c58427 into serde-rs:master Sep 25, 2025
14 checks passed
@dtolnay dtolnay deleted the inlinecoredoc branch September 25, 2025 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants