search

rust-lang-nursery / portability-wg

Coordination repository of the portability Working Group (WG)
42 stars 3 forks source link

Portability of documentation #8

Open jethrogb opened 6 years ago

jethrogb commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

I'd also like to use an epic

Since when does Rust have epics?

jyn514 commented 4 years ago

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

jyn514 commented 3 years ago

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 commented 3 years ago

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).