rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Rollup merge of #75330 - Nemo157:improve-doc-cfg-features, r=GuillaumeGomez

Browse Source 
Improve rendering of crate features via doc(cfg)

The current rendering of crate features with `doc(cfg(feature = ".."))` is verbose and unwieldy for users, `doc(cfg(target_feature = ".."))` is special-cased to make it render nicely, and a similar rendering can be applied to `doc(cfg(feature))` to make it easier for users to read.

I also added special casing of `all`/`any` cfgs consisting of just `feature`/`target-feature` to remove the repetitive "target/crate feature" prefix.

The downside of this current rendering is that there is no distinction between `feature` and `target_feature` in the shorthand display. IMO this is ok, or if anything `target_feature` should have a more verbose shorthand, because `doc(cfg(feature = ".."))` usage is going to vastly outstrip `doc(cfg(target_feature = ".."))` usage in non-stdlib crates when it eventually stabilizes (or even before that given the number of crates using `cfg_attr(docsrs)` like constructs).

## Previously

<img width="259" alt="Screenshot 2020-08-09 at 13 32 42" src="https://user-images.githubusercontent.com/81079/89731110-d090c000-da44-11ea-96fa-56adc6339123.png">
<img width="438" alt="image" src="https://user-images.githubusercontent.com/81079/89731116-d7b7ce00-da44-11ea-87c6-022d192d6eca.png">
<img width="765" alt="image" src="https://user-images.githubusercontent.com/81079/89731152-24030e00-da45-11ea-9552-1c270bff2729.png">
<img width="671" alt="image" src="https://user-images.githubusercontent.com/81079/89731158-28c7c200-da45-11ea-8acb-97d8a4ce00eb.png">

## Now

<img width="216" alt="image" src="https://user-images.githubusercontent.com/81079/89731123-e1d9cc80-da44-11ea-82a8-5900bd9448a5.png">
<img width="433" alt="image" src="https://user-images.githubusercontent.com/81079/89731127-e8684400-da44-11ea-9d18-572fd810f19f.png">
<img width="606" alt="image" src="https://user-images.githubusercontent.com/81079/89731162-2feed000-da45-11ea-98d2-8a88c364d903.png">
<img width="669" alt="image" src="https://user-images.githubusercontent.com/81079/89731991-ccb46c00-da4b-11ea-9416-cd20a3193826.png">

cc #43781
This commit is contained in:
Pietro Albini
2020-08-28 10:23:53 +02:00
committed by GitHub
parent 41aaa90c67 3328bd9a0f
commit 8730c2beb7
3 changed files with 154 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/librustdoc/html/render/mod.rs
View File

@@ -2130,8 +2130,8 @@ fn item_module(w: &mut Buffer, cx: &Context, item: &clean::Item, items: &[clean:
fn stability_tags(item: &clean::Item) -> String {
let mut tags = String::new();
fn tag_html(class: &str, contents: &str) -> String {
format!(r#"<span class="stab {}">{}</span>"#, class, contents)
fn tag_html(class: &str, title: &str, contents: &str) -> String {
format!(r#"<span class="stab {}" title="{}">{}</span>"#, class, Escape(title), contents)
}
// The trailing space after each tag is to space it properly against the rest of the docs.
@@ -2140,7 +2140,7 @@ fn stability_tags(item: &clean::Item) -> String {
if !stability::deprecation_in_effect(depr.is_since_rustc_version, depr.since.as_deref()) {
message = "Deprecation planned";
}
tags += &tag_html("deprecated", message);
tags += &tag_html("deprecated", "", message);
}
// The "rustc_private" crates are permanently unstable so it makes no sense
@@ -2151,11 +2151,11 @@ fn stability_tags(item: &clean::Item) -> String {
.map(|s| s.level == stability::Unstable && s.feature != "rustc_private")
== Some(true)
{
tags += &tag_html("unstable", "Experimental");
tags += &tag_html("unstable", "", "Experimental");
}
if let Some(ref cfg) = item.attrs.cfg {
tags += &tag_html("portability", &cfg.render_short_html());
tags += &tag_html("portability", &cfg.render_long_plain(), &cfg.render_short_html());
}
tags