Portability of documentation

[jethrogb]

rustdoc currently generates documentation only for a single target/configuration. When using conditional compilation, some functionality can go missing or can appear depending on the options chosen. For example, atomics of different sizes in core.

There is currently a rustdoc kludge to generate Windows and Unix documentation for std at the same time. Can something like this be extended to work for conditional compilation generally?

[Ericson2314]

This would required teaching the compiler to do "all simultaneous" (i.e. combinations of cfg'd code) name resolution, and maybe type checking too. It's a big change, but I think it's a worthwhile one to do eventually. That change, once implemented, would also trivially allow us to extend the portability lint to cover all cases, as came up in the RFC thread and on the call.

It's a long way off, but once we reach that point I'd also like to use an ~~epic~~ (edit epoch) to make the portability lint a hard error and part of type checking.

[retep998]

I'd also like to use an epic

Since when does Rust have epics?

[jyn514]

This is basically a duplicate of https://github.com/rust-lang/rust/issues/1998.

[jyn514]

This would required teaching the compiler to do "all simultaneous" (i.e. combinations of cfg'd code) name resolution, and maybe type checking too. It's a big change, but I think it's a worthwhile one to do eventually. That change, once implemented, would also trivially allow us to extend the portability lint to cover all cases, as came up in the RFC thread and on the call.

Note the way rustdoc does this is specifically by not doing name resolution or type checking (https://github.com/rust-lang/rust/pull/73566, https://github.com/rust-lang/rust/pull/75127). Having combinations of cfg'd code is incompatible with either of those two (https://github.com/rust-lang/rfcs/pull/2963#issuecomment-669515931), and I don't see how could work even in theory.

[jyn514]

There is currently a rustdoc kludge to generate Windows and Unix documentation for std at the same time. Can something like this be extended to work for conditional compilation generally?

Yes, nothing about the kludge is specific to cfg(windows) or cfg(unix), it will work for any combination of cfgs as long as it doesn't require type-checking function bodies (and I haven't found a case since https://github.com/rust-lang/rust/pull/75127 that requires checking bodies).