Add rustdoc-specific attribute to make type aliases less alias-y?

1

Imagine type alias which is used to hide several levels of generics:

type Foo = Wrapper<Bar<u32>, Option<u64>>;

Currently rustdoc simply shows the alias definitions and that's it. You can not see at a glance traits implemented by alias and docs for them, you have to look into Wrapper/Bar docs and piece everything in your head, which is obviously quite inefficient. Even worse, in some cases it performs unexpected de-aliasing which can significantly harm readability. The latter problem is especially bad with typenum (in some cases we still have to use it, since const generics are not powerful enough) where a simple U32 in docs gets blown into:

UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>

What about adding an attribute which would force rustdoc to treat type aliases like independent types during doc generation? Meaning it would show traits implemented for aliases marked by the attribute and will not de-alias their use in other docs.

Or maybe such behavior should become the default one?

6 Likes
2

Something like #[doc(opaque)] would be nice. The documentation could treat such an alias as a TAIT where the traits implemented would be exactly those implemented by the aliased type. This would probably require compiler support though?

The attribute could also be useful to "opacify" some structs or especially enums that have public members, essentially marking all members as #[doc(hidden)].

3

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.