Skip to content

Rename "stability" CSS class to "item-info" and combine document_stability with document_short #79340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 29, 2020
+77 −58
Merged

Rename "stability" CSS class to "item-info" and combine document_stability with document_short #79340

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
caf6c57
Rename "stability" CSS class to "item-info"
GuillaumeGomez Nov 23, 2020
be0484b
Clean up document_item_info calls
GuillaumeGomez Nov 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 46 additions & 28 deletions src/librustdoc/html/render/mod.rs
View file
Original file line number Diff line number Diff line change
@@ -1844,7 +1844,7 @@ fn document(w: &mut Buffer, cx: &Context, item: &clean::Item, parent: Option<&cl
if let Some(ref name) = item.name {
info!("Documenting {}", name);
}
document_stability(w, cx, item, false, parent);
document_item_info(w, cx, item, false, parent);
document_full(w, item, cx, "", false);
Comment on lines +1847 to 1848
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are these separate? Are there cases when you want one but not the other?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, there isn't. Let's call document_item_info inside document full. Great catch!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hum actually we can't really do that in a straightforward way because in some cases, we add the information on the parent. For example:

document_item_info(w, cx, item, is_hidden, Some(parent));
if show_def_docs {
    document_full(w, item, cx, "", is_hidden);
}

And it's in multiple places. document_short has the same "problem".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you pass in show_def_docs as a parameter? Then it would have the same behavior, but make it hard to forget about document_item_info.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine by me!

}

@@ -1880,10 +1880,17 @@ fn render_markdown(
fn document_short(
w: &mut Buffer,
item: &clean::Item,
cx: &Context,
link: AssocItemLink<'_>,
prefix: &str,
is_hidden: bool,
parent: Option<&clean::Item>,
show_def_docs: bool,
) {
document_item_info(w, cx, item, is_hidden, parent);
if !show_def_docs {
return;
}
if let Some(s) = item.doc_value() {
let mut summary_html = MarkdownSummaryLine(s, &item.links()).into_string();

@@ -1928,18 +1935,23 @@ fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context, prefix: &str,
}
}

fn document_stability(
/// Add extra information about an item such as:
///
/// * Stability
/// * Deprecated
/// * Required features (through the `doc_cfg` feature)
fn document_item_info(
w: &mut Buffer,
cx: &Context,
item: &clean::Item,
is_hidden: bool,
parent: Option<&clean::Item>,
) {
let stabilities = short_stability(item, cx, parent);
if !stabilities.is_empty() {
write!(w, "<div class=\"stability{}\">", if is_hidden { " hidden" } else { "" });
for stability in stabilities {
write!(w, "{}", stability);
let item_infos = short_item_info(item, cx, parent);
if !item_infos.is_empty() {
write!(w, "<div class=\"item-info{}\">", if is_hidden { " hidden" } else { "" });
for info in item_infos {
write!(w, "{}", info);
}
write!(w, "</div>");
}
@@ -2194,7 +2206,7 @@ fn item_module(w: &mut Buffer, cx: &Context, item: &clean::Item, items: &[clean:
<td class=\"docblock-short\">{stab_tags}{docs}</td>\
</tr>",
name = *myitem.name.as_ref().unwrap(),
stab_tags = stability_tags(myitem, item),
stab_tags = extra_info_tags(myitem, item),
docs = MarkdownSummaryLine(doc_value, &myitem.links()).into_string(),
class = myitem.type_(),
add = add,
@@ -2216,9 +2228,9 @@ fn item_module(w: &mut Buffer, cx: &Context, item: &clean::Item, items: &[clean:
}
}

/// Render the stability and deprecation tags that are displayed in the item's summary at the
/// module level.
fn stability_tags(item: &clean::Item, parent: &clean::Item) -> String {
/// Render the stability, deprecation and portability tags that are displayed in the item's summary
/// at the module level.
fn extra_info_tags(item: &clean::Item, parent: &clean::Item) -> String {
let mut tags = String::new();

fn tag_html(class: &str, title: &str, contents: &str) -> String {
@@ -2271,10 +2283,10 @@ fn portability(item: &clean::Item, parent: Option<&clean::Item>) -> Option<Strin
Some(format!("<div class=\"stab portability\">{}</div>", cfg?.render_long_html()))
}

/// Render the stability and/or deprecation warning that is displayed at the top of the item's
/// documentation.
fn short_stability(item: &clean::Item, cx: &Context, parent: Option<&clean::Item>) -> Vec<String> {
let mut stability = vec![];
/// Render the stability, deprecation and portability information that is displayed at the top of
/// the item's documentation.
fn short_item_info(item: &clean::Item, cx: &Context, parent: Option<&clean::Item>) -> Vec<String> {
let mut extra_info = vec![];
let error_codes = cx.shared.codes;

if let Some(Deprecation { ref note, ref since, is_since_rustc_version }) = item.deprecation {
@@ -2301,7 +2313,7 @@ fn short_stability(item: &clean::Item, cx: &Context, parent: Option<&clean::Item
);
message.push_str(&format!(": {}", html.into_string()));
}
stability.push(format!(
extra_info.push(format!(
"<div class=\"stab deprecated\"><span class=\"emoji\">👎</span> {}</div>",
message,
));
@@ -2345,14 +2357,14 @@ fn short_stability(item: &clean::Item, cx: &Context, parent: Option<&clean::Item
);
}

stability.push(format!("<div class=\"stab unstable\">{}</div>", message));
extra_info.push(format!("<div class=\"stab unstable\">{}</div>", message));
}

if let Some(portability) = portability(item, parent) {
stability.push(portability);
extra_info.push(portability);
}

stability
extra_info
}

fn item_constant(w: &mut Buffer, cx: &Context, it: &clean::Item, c: &clean::Constant) {
@@ -3703,7 +3715,7 @@ fn render_impl(

if trait_.is_some() {
if let Some(portability) = portability(&i.impl_item, Some(parent)) {
write!(w, "<div class=\"stability\">{}</div>", portability);
write!(w, "<div class=\"item-info\">{}</div>", portability);
}
}

@@ -3801,26 +3813,32 @@ fn render_impl(
if let Some(it) = t.items.iter().find(|i| i.name == item.name) {
// We need the stability of the item from the trait
// because impls can't have a stability.
document_stability(w, cx, it, is_hidden, Some(parent));
if item.doc_value().is_some() {
document_item_info(w, cx, it, is_hidden, Some(parent));
document_full(w, item, cx, "", is_hidden);
} else if show_def_docs {
} else {
// In case the item isn't documented,
// provide short documentation from the trait.
document_short(w, it, link, "", is_hidden);
document_short(
w,
it,
cx,
link,
"",
is_hidden,
Some(parent),
show_def_docs,
);
}
}
} else {
document_stability(w, cx, item, is_hidden, Some(parent));
document_item_info(w, cx, item, is_hidden, Some(parent));
if show_def_docs {
document_full(w, item, cx, "", is_hidden);
}
}
} else {
document_stability(w, cx, item, is_hidden, Some(parent));
if show_def_docs {
document_short(w, item, link, "", is_hidden);
}
document_short(w, item, cx, link, "", is_hidden, Some(parent), show_def_docs);
}
}
}
17 changes: 9 additions & 8 deletions src/librustdoc/html/static/main.js
View file
Original file line number Diff line number Diff line change
@@ -2266,7 +2266,7 @@ function defocusSearchBar() {
}
}
var ns = n.nextElementSibling;
while (ns && (hasClass(ns, "docblock") || hasClass(ns, "stability"))) {
while (ns && (hasClass(ns, "docblock") || hasClass(ns, "item-info"))) {
if (addOrRemove) {
addClass(ns, "hidden-by-impl-hider");
} else {
@@ -2282,7 +2282,7 @@ function defocusSearchBar() {
var action = mode;
if (hasClass(toggle.parentNode, "impl") === false) {
relatedDoc = toggle.parentNode.nextElementSibling;
if (hasClass(relatedDoc, "stability")) {
if (hasClass(relatedDoc, "item-info")) {
relatedDoc = relatedDoc.nextElementSibling;
}
if (hasClass(relatedDoc, "docblock") || hasClass(relatedDoc, "sub-variant")) {
@@ -2332,16 +2332,17 @@ function defocusSearchBar() {
var dontApplyBlockRule = toggle.parentNode.parentNode.id !== "main";
if (action === "show") {
removeClass(relatedDoc, "fns-now-collapsed");
// Stability information is never hidden.
if (hasClass(docblock, "stability") === false) {
// Stability/deprecation/portability information is never hidden.
if (hasClass(docblock, "item-info") === false) {
removeClass(docblock, "hidden-by-usual-hider");
}
onEachLazy(toggle.childNodes, adjustToggle(false, dontApplyBlockRule));
onEachLazy(relatedDoc.childNodes, implHider(false, dontApplyBlockRule));
} else if (action === "hide") {
addClass(relatedDoc, "fns-now-collapsed");
// Stability information should be shown even when detailed info is hidden.
if (hasClass(docblock, "stability") === false) {
// Stability/deprecation/portability information should be shown even when detailed
// info is hidden.
if (hasClass(docblock, "item-info") === false) {
addClass(docblock, "hidden-by-usual-hider");
}
onEachLazy(toggle.childNodes, adjustToggle(true, dontApplyBlockRule));
@@ -2445,7 +2446,7 @@ function defocusSearchBar() {

var func = function(e) {
var next = e.nextElementSibling;
if (next && hasClass(next, "stability")) {
if (next && hasClass(next, "item-info")) {
next = next.nextElementSibling;
}
if (!next) {
@@ -2462,7 +2463,7 @@ function defocusSearchBar() {

var funcImpl = function(e) {
var next = e.nextElementSibling;
if (next && hasClass(next, "stability")) {
if (next && hasClass(next, "item-info")) {
next = next.nextElementSibling;
}
if (next && hasClass(next, "docblock")) {
18 changes: 9 additions & 9 deletions src/librustdoc/html/static/rustdoc.css
View file
Original file line number Diff line number Diff line change
@@ -553,21 +553,21 @@ h4 > code, h3 > code, .invisible > code {
border: none;
}

.content .stability code {
.content .item-info code {
font-size: 90%;
}

.content .stability {
.content .item-info {
position: relative;
margin-left: 33px;
margin-top: -13px;
}

.sub-variant > div > .stability {
.sub-variant > div > .item-info {
margin-top: initial;
}

.content .stability::before {
.content .item-info::before {
content: '⬑';
font-size: 25px;
position: absolute;
@@ -579,23 +579,23 @@ h4 > code, h3 > code, .invisible > code {
margin-left: 20px;
}

.content .impl-items .docblock, .content .impl-items .stability {
.content .impl-items .docblock, .content .impl-items .item-info {
margin-bottom: .6em;
}

.content .impl-items > .stability {
.content .impl-items > .item-info {
margin-left: 40px;
}

.methods > .stability, .content .impl-items > .stability {
.methods > .item-info, .content .impl-items > .item-info {
margin-top: -8px;
}

.impl-items {
flex-basis: 100%;
}

#main > .stability {
#main > .item-info {
margin-top: 0;
}

@@ -655,7 +655,7 @@ a {
}

.docblock a:not(.srclink):not(.test-arrow):hover,
.docblock-short a:not(.srclink):not(.test-arrow):hover, .stability a {
.docblock-short a:not(.srclink):not(.test-arrow):hover, .item-info a {
text-decoration: underline;
}

4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/ayu.css
View file
Original file line number Diff line number Diff line change
@@ -166,7 +166,7 @@ pre {
color: #c5c5c5;
}

.content .stability::before { color: #ccc; }
.content .item-info::before { color: #ccc; }

.content span.foreigntype, .content a.foreigntype { color: #ef57ff; }
.content span.union, .content a.union { color: #98a01c; }
@@ -219,7 +219,7 @@ a {
}

.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow),
.docblock-short a:not(.srclink):not(.test-arrow), .stability a,
.docblock-short a:not(.srclink):not(.test-arrow), .item-info a,
#help a {
color: #39AFD7;
}
4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/dark.css
View file
Original file line number Diff line number Diff line change
@@ -136,7 +136,7 @@ pre {
.content .highlighted.primitive { background-color: #00708a; }
.content .highlighted.keyword { background-color: #884719; }

.content .stability::before { color: #ccc; }
.content .item-info::before { color: #ccc; }

.content span.enum, .content a.enum, .block a.current.enum { color: #82b089; }
.content span.struct, .content a.struct, .block a.current.struct { color: #2dbfb8; }
@@ -177,7 +177,7 @@ a {
}

.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow),
.docblock-short a:not(.srclink):not(.test-arrow), .stability a,
.docblock-short a:not(.srclink):not(.test-arrow), .item-info a,
#help a {
color: #D2991D;
}
4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/light.css
View file
Original file line number Diff line number Diff line change
@@ -134,7 +134,7 @@ pre {
.content .highlighted.primitive { background-color: #9aecff; }
.content .highlighted.keyword { background-color: #f99650; }

.content .stability::before { color: #ccc; }
.content .item-info::before { color: #ccc; }

.content span.enum, .content a.enum, .block a.current.enum { color: #508157; }
.content span.struct, .content a.struct, .block a.current.struct { color: #ad448e; }
@@ -175,7 +175,7 @@ a {
}

.docblock:not(.type-decl) a:not(.srclink):not(.test-arrow),
.docblock-short a:not(.srclink):not(.test-arrow), .stability a,
.docblock-short a:not(.srclink):not(.test-arrow), .item-info a,
#help a {
color: #3873AD;
}
12 changes: 6 additions & 6 deletions src/test/rustdoc/doc-cfg.rs
View file
Original file line number Diff line number Diff line change
@@ -2,28 +2,28 @@
#![feature(target_feature, cfg_target_feature)]

// @has doc_cfg/struct.Portable.html
// @!has - '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' ''
// @!has - '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' ''
// @has - '//*[@id="method.unix_and_arm_only_function"]' 'fn unix_and_arm_only_function()'
// @has - '//*[@class="stab portability"]' 'This is supported on Unix and ARM only.'
pub struct Portable;

// @has doc_cfg/unix_only/index.html \
// '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' \
// '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix only.'
// @matches - '//*[@class="module-item"]//*[@class="stab portability"]' '\AARM\Z'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(unix))]
pub mod unix_only {
// @has doc_cfg/unix_only/fn.unix_only_function.html \
// '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' \
// '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix only.'
// @count - '//*[@class="stab portability"]' 1
pub fn unix_only_function() {
content::should::be::irrelevant();
}

// @has doc_cfg/unix_only/trait.ArmOnly.html \
// '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' \
// '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix and ARM only.'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(target_arch = "arm"))]
@@ -44,15 +44,15 @@ pub mod unix_only {
// @matches - '//*[@class="module-item"]//*[@class="stab portability"]' '\Aavx\Z'

// @has doc_cfg/fn.uses_target_feature.html
// @has - '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' \
// @has - '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported with target feature avx only.'
#[target_feature(enable = "avx")]
pub unsafe fn uses_target_feature() {
content::should::be::irrelevant();
}

// @has doc_cfg/fn.uses_cfg_target_feature.html
// @has - '//*[@id="main"]/*[@class="stability"]/*[@class="stab portability"]' \
// @has - '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported with target feature avx only.'
#[doc(cfg(target_feature = "avx"))]
pub fn uses_cfg_target_feature() {
2 changes: 1 addition & 1 deletion src/test/rustdoc/stability.rs
View file
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@

pub struct Unstable {
// @has stability/struct.Unstable.html \
// '//div[@class="stability"]//div[@class="stab unstable"]' \
// '//div[@class="item-info"]//div[@class="stab unstable"]' \
// 'This is a nightly-only experimental API'
// @count stability/struct.Unstable.html '//span[@class="stab unstable"]' 0
pub foo: u32,