cargo doc generates ugly documentation

[nullchinchilla]

cargo doc seems to generate documentation for the trait based on the expanded code, rather than the pre-expansion code. e.g.

Is this fundamentally unfixable, or is there some way of getting cargo doc to display the trait with the pre-expansion form, document the methods as async fn etc?

[dtolnay]

This would need to be a feature request for rustdoc to support emitting async fn in traits. Currently there is no way.

[nullchinchilla]

That is very unfortunate. Is the only way manually documenting the async fns then?

[WhyNotHugo]

Any known workarounds for this one?

[dtolnay]

Yeah you can do:

# Cargo.toml

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "docs_rs"]

// lib.rs

#![cfg_attr(docs_rs, feature(async_fn_in_trait))]

#[cfg_attr(not(docs_rs), async_trait::async_trait)]
pub trait Trait {
    async fn f();
}

[eaufavor]

I don't think this doc trick works universally anymore since the official async trait is stabilized but with a lot limitations. In other words, some of the traits I created are not valid (can no longer compile) under the official async trait. So it might be the time to reconsider this ticket.