Are type definitions "expanded" on docs.rs?

help
1

On docs.rs, it seems that type definitions are "expanded", instead of displaying their "original" definition in the source code.

For example:

fn ensure_migrations_table(&mut self) -> BoxFuture<'_, Result<(), MigrateError>>;

Becomes:

pub fn ensure_migrations_table(
    &mut self
) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send, Global>>

Source: sqlx::migrate::Migrate - Rust

Any way to avoid this? Is it by design?

2

I'm guessing this happens because the type alias isn't a publicly accessible part of the current crate.

Often type aliases are just a way to simplify a type name so the designers of rustdoc may have decided you get more value by "inlining" it.

1 Like
3

BoxFuture comes from a non-documented crate in this case. (docs.rs documents every crate independently unlike local cargo doc runs)

4

What do you mean by "non-documented crate"?

It seems documented:

Do you mean it's undocumented from the point of view of sqlx documentation because docs.rs documents every crate independently?

5

Normally when you run cargo doc all dependencies are documented first and then rustdoc can find the existing documentationbfor the dependencies when documenting the current crate. This allows it to for example edit this documentation to list implementations of traits that are part of the current crate, but are either for traits or types defined in those dependencies. On docs.rs every crate is documented in isolation without it's dependencies being documented in the same documentation directory, this means that rustdoc doesn't have access to documentation for dependencies and as such can't edit their documentation or adapt documentation of the current crate accordingly. It is possible that in this case rustdoc chooses to expand BoxFuture due to not being able to access the documentation for the crate defining BoxFuture.

2 Likes
6

It is possible that in this case rustdoc chooses to expand BoxFuture due to not being able to access the documentation for the crate defining BoxFuture.

I see the idea here, but that makes type definitions much more complex than how they have been written by the crate author. I don't see the benefit in terms of documentation (since this is the goal).

7

It comes from a crate which has an html-root-url to link to though, you can see many other instances of crates linking across to different crates on docs.rs. In general I would expect there to be no difference in rendering whether the other crate is locally documented (like cargo doc does by default) or remotely linked (like docs.rs, or cargo doc --no-deps -Zrustdoc-map).

AFAIK rustdoc always inlines external type aliases, even if you have an inline re-export, and even sometimes for internal type aliases. There's a few open issues around this, I feel like it's just a longstanding bug, probably because the metadata for the external crate doesn't contain the data to say it was a type alias, it may have already been replaced with the expanded form before rustdoc ever sees it.

1 Like
8

If you can push changes to sqlx, you could, for this very example, locally define BoxFuture:

pub type BoxFuture<'lt, Output> =
    ::futures::future::BoxFuture<'lt, Output>
// or inline the definition:
    ::core::pin::Pin<Box<
        dyn 'lt + Send + ::core::future::Future<Output = Output>
    >>
;

That way rustdoc may actually use the type alias since it is local and thus knows about it when doc-compiling that crate in isolation.

9

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.