rustdoc doc(cfg) rendering gets ugly with long cfg expressions
jplatte opened this issue · 9 comments
I think long cfg expressions should be broken across multiple lines. I saw this cause issues here:
What if we inserted zero width spaces after the keywords? So after each or we insert a zero width space U+200B (see the example in my blog).
Maybe we would have to wrap each name in a span too but I would have to experiment a bit.
Then each expression would try to stay as an inline-block and then break the line on the keywords (like and, or, not, ...)
If we start having "groups", not sure if it'll work well. But definitely worth a try!
I started a test case with a long and complicated expression that results in this image:
#[cfg(any(feature="long-feature-flag-name",feature="appservice-api", not(feature="clientservice-c"), all(feature="clientservice-rust",feature="identity-clientservice-embedded-something-something-i-need-something-long-to-testing")))]
#[no_mangle]
/// This is a function that requires a lot of flags
pub fn rarely_used_function() {}
Currently combining a lot of short features is very unreadable and not's are hard to spot.
With just span code { display: block; } it gets a lot more readable, but since the braces get lost in translation it is not clear which flags are binding with or, not or and respectively.
What if we display a little tree diagram? For most cases that would probably result in a short list with an and or an or in the beginning.
Another idea could be to not draw the tree but to have visible boxes encasing the respective flags.
What do you think?
I need to see things to be able to make my own opinion on which approach is better. 😄 But maybe @jsha has an idea?
Maybe it could show "any of"/"all of" on longer chains (say 3+)? I don't think there's a ton that can realistically be done here — a long cfg is going to result in a long doc cfg.
There are a lot of things that can be done. For example, for more than 3 items, we could show only the 3 first and show the rest on click. It's mostly about how to display things.
The original case has gotten a lot better, the actual doc string now gets ~60% of the horizontal space rather than ~30%:
Rendering has degraded again (even though the documented cfg expressions themselves have become shorter):
