Skip to content
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

Jump to bottom

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

Merged
merged 2 commits into from
Nov 29, 2020
Merged

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

Show file tree
Hide file tree
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!

}

Expand Down Expand Up @@ -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();

Expand Down Expand Up @@ -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);
jyn514 marked this conversation as resolved.
Show resolved Hide resolved
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>");
}
Expand Down Expand Up @@ -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,
Expand All @@ -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 {
Expand Down Expand Up @@ -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 {
Expand All @@ -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,
));
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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);
}
}

Expand Down Expand Up @@ -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);
}
}
}
Expand Down
17 changes: 9 additions & 8 deletions src/librustdoc/html/static/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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")) {
Expand Down Expand Up @@ -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));
Expand Down Expand Up @@ -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) {
Expand All @@ -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")) {
Expand Down
18 changes: 9 additions & 9 deletions src/librustdoc/html/static/rustdoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand Down
4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/ayu.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand Down Expand Up @@ -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;
}
Expand Down
4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/dark.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand Down Expand Up @@ -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;
}
Expand Down
4 changes: 2 additions & 2 deletions src/librustdoc/html/static/themes/light.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand Down Expand Up @@ -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;
}
Expand Down
12 changes: 6 additions & 6 deletions src/test/rustdoc/doc-cfg.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"))]
Expand All @@ -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() {
Expand Down
Loading