diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/librustdoc/clean/mod.rs | 48 | ||||
| -rw-r--r-- | src/librustdoc/html/render.rs | 200 | ||||
| -rw-r--r-- | src/librustdoc/html/static/rustdoc.css | 2 | ||||
| -rw-r--r-- | src/librustdoc/html/static/themes/dark.css | 5 | ||||
| -rw-r--r-- | src/librustdoc/html/static/themes/light.css | 5 | ||||
| -rw-r--r-- | src/test/rustdoc/deprecated.rs | 22 | ||||
| -rw-r--r-- | src/test/rustdoc/internal.rs | 10 | ||||
| -rw-r--r-- | src/test/rustdoc/issue-27759.rs | 8 | ||||
| -rw-r--r-- | src/test/rustdoc/issue-32374.rs | 10 |
9 files changed, 183 insertions, 127 deletions
diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index f42b19ed139..01ead05999b 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -478,7 +478,7 @@ impl Item { classes.push("unstable"); } - if !s.deprecated_since.is_empty() { + if s.deprecation.is_some() { classes.push("deprecated"); } @@ -503,6 +503,15 @@ impl Item { pub fn type_(&self) -> ItemType { ItemType::from(self) } + + /// Returns the info in the item's `#[deprecated]` or `#[rustc_deprecated]` attributes. + /// + /// If the item is not deprecated, returns `None`. + pub fn deprecation(&self) -> Option<&Deprecation> { + self.deprecation + .as_ref() + .or_else(|| self.stability.as_ref().and_then(|s| s.deprecation.as_ref())) + } } #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] @@ -3844,40 +3853,37 @@ impl Clean<Item> for doctree::ProcMacro { #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Stability { pub level: stability::StabilityLevel, - pub feature: String, + pub feature: Option<String>, pub since: String, - pub deprecated_since: String, - pub deprecated_reason: String, - pub unstable_reason: String, - pub issue: Option<u32> + pub deprecation: Option<Deprecation>, + pub unstable_reason: Option<String>, + pub issue: Option<u32>, } #[derive(Clone, RustcEncodable, RustcDecodable, Debug)] pub struct Deprecation { - pub since: String, - pub note: String, + pub since: Option<String>, + pub note: Option<String>, } impl Clean<Stability> for attr::Stability { fn clean(&self, _: &DocContext) -> Stability { Stability { level: stability::StabilityLevel::from_attr_level(&self.level), - feature: self.feature.to_string(), + feature: Some(self.feature.to_string()).filter(|f| !f.is_empty()), since: match self.level { attr::Stable {ref since} => since.to_string(), _ => String::new(), }, - deprecated_since: match self.rustc_depr { - Some(attr::RustcDeprecation {ref since, ..}) => since.to_string(), - _=> String::new(), - }, - deprecated_reason: match self.rustc_depr { - Some(ref depr) => depr.reason.to_string(), - _ => String::new(), - }, + deprecation: self.rustc_depr.as_ref().map(|d| { + Deprecation { + note: Some(d.reason.to_string()).filter(|r| !r.is_empty()), + since: Some(d.since.to_string()).filter(|d| !d.is_empty()), + } + }), unstable_reason: match self.level { - attr::Unstable { reason: Some(ref reason), .. } => reason.to_string(), - _ => String::new(), + attr::Unstable { reason: Some(ref reason), .. } => Some(reason.to_string()), + _ => None, }, issue: match self.level { attr::Unstable {issue, ..} => Some(issue), @@ -3896,8 +3902,8 @@ impl<'a> Clean<Stability> for &'a attr::Stability { impl Clean<Deprecation> for attr::Deprecation { fn clean(&self, _: &DocContext) -> Deprecation { Deprecation { - since: self.since.as_ref().map_or(String::new(), |s| s.to_string()), - note: self.note.as_ref().map_or(String::new(), |s| s.to_string()), + since: self.since.map(|s| s.to_string()).filter(|s| !s.is_empty()), + note: self.note.map(|n| n.to_string()).filter(|n| !n.is_empty()), } } } diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index fdc4d5d75b3..2ee4db3a539 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -65,7 +65,7 @@ use rustc::hir; use rustc::util::nodemap::{FxHashMap, FxHashSet}; use rustc_data_structures::flock; -use clean::{self, AttributesExt, GetDefId, SelfTy, Mutability}; +use clean::{self, AttributesExt, Deprecation, GetDefId, SelfTy, Mutability}; use config::RenderOptions; use doctree; use fold::DocFolder; @@ -2458,7 +2458,7 @@ fn document_full(w: &mut fmt::Formatter, item: &clean::Item, fn document_stability(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item, is_hidden: bool) -> fmt::Result { - let stabilities = short_stability(item, cx, true); + let stabilities = short_stability(item, cx); if !stabilities.is_empty() { write!(w, "<div class='stability{}'>", if is_hidden { " hidden" } else { "" })?; for stability in stabilities { @@ -2651,18 +2651,6 @@ fn item_module(w: &mut fmt::Formatter, cx: &Context, _ => { if myitem.name.is_none() { continue } - let stabilities = short_stability(myitem, cx, false); - - let stab_docs = if !stabilities.is_empty() { - stabilities.iter() - .map(|s| format!("[{}]", s)) - .collect::<Vec<_>>() - .as_slice() - .join(" ") - } else { - String::new() - }; - let unsafety_flag = match myitem.inner { clean::FunctionItem(ref func) | clean::ForeignFunctionItem(ref func) if func.header.unsafety == hir::Unsafety::Unsafe => { @@ -2683,11 +2671,11 @@ fn item_module(w: &mut fmt::Formatter, cx: &Context, <tr class='{stab}{add}module-item'>\ <td><a class=\"{class}\" href=\"{href}\" \ title='{title}'>{name}</a>{unsafety_flag}</td>\ - <td class='docblock-short'>{stab_docs}{docs}\ + <td class='docblock-short'>{stab_tags}{docs}\ </td>\ </tr>", name = *myitem.name.as_ref().unwrap(), - stab_docs = stab_docs, + stab_tags = stability_tags(myitem), docs = MarkdownSummaryLine(doc_value, &myitem.links()), class = myitem.type_(), add = add, @@ -2714,101 +2702,123 @@ fn item_module(w: &mut fmt::Formatter, cx: &Context, Ok(()) } -fn short_stability(item: &clean::Item, cx: &Context, show_reason: bool) -> Vec<String> { +/// Render the stability and deprecation tags that are displayed in the item's summary at the +/// module level. +fn stability_tags(item: &clean::Item) -> String { + let mut tags = String::new(); + + // The trailing space after each tag is to space it properly against the rest of the docs. + if item.deprecation().is_some() { + tags.push_str("[<div class='stab deprecated'>Deprecated</div>] "); + } + + if let Some(stab) = item + .stability + .as_ref() + .filter(|s| s.level == stability::Unstable) + { + if stab.feature.as_ref().map(|s| &**s) == Some("rustc_private") { + tags.push_str("[<div class='stab internal'>Internal</div>] "); + } else { + tags.push_str("[<div class='stab unstable'>Experimental</div>] "); + } + } + + if let Some(ref cfg) = item.attrs.cfg { + tags.push_str(&format!( + "[<div class='stab portability'>{}</div>] ", + cfg.render_short_html() + )); + } + + tags +} + +/// 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) -> Vec<String> { let mut stability = vec![]; let error_codes = ErrorCodes::from(UnstableFeatures::from_environment().is_nightly_build()); - if let Some(stab) = item.stability.as_ref() { - let deprecated_reason = if show_reason && !stab.deprecated_reason.is_empty() { - format!(": {}", stab.deprecated_reason) + if let Some(Deprecation { since, note }) = &item.deprecation() { + let mut message = if let Some(since) = since { + if stability::deprecation_in_effect(since) { + format!("Deprecated since {}", Escape(since)) + } else { + format!("Deprecating in {}", Escape(since)) + } } else { - String::new() + String::from("Deprecated") }; - if !stab.deprecated_since.is_empty() { - let since = if show_reason { - format!(" since {}", Escape(&stab.deprecated_since)) - } else { - String::new() - }; + + if let Some(note) = note { let mut ids = cx.id_map.borrow_mut(); - let html = MarkdownHtml(&deprecated_reason, RefCell::new(&mut ids), error_codes); - let text = if stability::deprecation_in_effect(&stab.deprecated_since) { - format!("Deprecated{}{}", since, html) + let html = MarkdownHtml(¬e, RefCell::new(&mut ids), error_codes); + message.push_str(&format!(": {}", html)); + } + stability.push(format!("<div class='stab deprecated'>{}</div>", message)); + } + + if let Some(stab) = item + .stability + .as_ref() + .filter(|stab| stab.level == stability::Unstable) + { + let is_rustc_private = stab.feature.as_ref().map(|s| &**s) == Some("rustc_private"); + + let mut message = if is_rustc_private { + "<span class='emoji'>⚙️</span> This is an internal compiler API." + } else { + "<span class='emoji'>🔬</span> This is a nightly-only experimental API." + } + .to_owned(); + + if let Some(feature) = stab.feature.as_ref() { + let mut feature = format!("<code>{}</code>", Escape(&feature)); + if let (Some(url), Some(issue)) = (&cx.shared.issue_tracker_base_url, stab.issue) { + feature.push_str(&format!( + " <a href=\"{url}{issue}\">#{issue}</a>", + url = url, + issue = issue + )); + } + + message.push_str(&format!(" ({})", feature)); + } + + if let Some(unstable_reason) = &stab.unstable_reason { + // Provide a more informative message than the compiler help. + let unstable_reason = if is_rustc_private { + "This crate is being loaded from the sysroot, a permanently unstable location \ + for private compiler dependencies. It is not intended for general use. Prefer \ + using a public version of this crate from \ + [crates.io](https://crates.io) via [`Cargo.toml`]\ + (https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)." } else { - format!("Deprecating in {}{}", Escape(&stab.deprecated_since), html) + unstable_reason }; - stability.push(format!("<div class='stab deprecated'>{}</div>", text)) - }; - if stab.level == stability::Unstable { - if show_reason { - let unstable_extra = match (!stab.feature.is_empty(), - &cx.shared.issue_tracker_base_url, - stab.issue) { - (true, &Some(ref tracker_url), Some(issue_no)) if issue_no > 0 => - format!(" (<code>{} </code><a href=\"{}{}\">#{}</a>)", - Escape(&stab.feature), tracker_url, issue_no, issue_no), - (false, &Some(ref tracker_url), Some(issue_no)) if issue_no > 0 => - format!(" (<a href=\"{}{}\">#{}</a>)", Escape(&tracker_url), issue_no, - issue_no), - (true, ..) => - format!(" (<code>{}</code>)", Escape(&stab.feature)), - _ => String::new(), - }; - if stab.unstable_reason.is_empty() { - stability.push(format!("<div class='stab unstable'>\ - <span class=microscope>🔬</span> \ - This is a nightly-only experimental API. {}\ - </div>", - unstable_extra)); - } else { - let mut ids = cx.id_map.borrow_mut(); - let text = format!("<summary><span class=microscope>🔬</span> \ - This is a nightly-only experimental API. {}\ - </summary>{}", - unstable_extra, - MarkdownHtml( - &stab.unstable_reason, - RefCell::new(&mut ids), - error_codes)); - stability.push(format!("<div class='stab unstable'><details>{}</details></div>", - text)); - } - } else { - stability.push("<div class='stab unstable'>Experimental</div>".to_string()) - } - }; - } else if let Some(depr) = item.deprecation.as_ref() { - let note = if show_reason && !depr.note.is_empty() { - format!(": {}", depr.note) - } else { - String::new() - }; - let since = if show_reason && !depr.since.is_empty() { - format!(" since {}", Escape(&depr.since)) - } else { - String::new() - }; + let mut ids = cx.id_map.borrow_mut(); + message = format!( + "<details><summary>{}</summary>{}</details>", + message, + MarkdownHtml(&unstable_reason, RefCell::new(&mut ids), error_codes) + ); + } - let mut ids = cx.id_map.borrow_mut(); - let text = if stability::deprecation_in_effect(&depr.since) { - format!("Deprecated{}{}", - since, - MarkdownHtml(¬e, RefCell::new(&mut ids), error_codes)) + let class = if is_rustc_private { + "internal" } else { - format!("Deprecating in {}{}", - Escape(&depr.since), - MarkdownHtml(¬e, RefCell::new(&mut ids), error_codes)) + "unstable" }; - stability.push(format!("<div class='stab deprecated'>{}</div>", text)) + stability.push(format!("<div class='stab {}'>{}</div>", class, message)); } if let Some(ref cfg) = item.attrs.cfg { - stability.push(format!("<div class='stab portability'>{}</div>", if show_reason { + stability.push(format!( + "<div class='stab portability'>{}</div>", cfg.render_long_html() - } else { - cfg.render_short_html() - })); + )); } stability diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css index 7a3682503f7..3958986e492 100644 --- a/src/librustdoc/html/static/rustdoc.css +++ b/src/librustdoc/html/static/rustdoc.css @@ -769,7 +769,7 @@ body.blur > :not(#help) { display: list-item; } -.stab .microscope { +.stab .emoji { font-size: 1.5em; } diff --git a/src/librustdoc/html/static/themes/dark.css b/src/librustdoc/html/static/themes/dark.css index 2cd1a858089..be3ffed2b26 100644 --- a/src/librustdoc/html/static/themes/dark.css +++ b/src/librustdoc/html/static/themes/dark.css @@ -174,6 +174,10 @@ a { color: #D2991D; } +.stab.internal a { + color: #304FFE; +} + a.test-arrow { color: #dedede; } @@ -199,6 +203,7 @@ a.test-arrow { } .stab.unstable { background: #FFF5D6; border-color: #FFC600; color: #404040; } +.stab.internal { background: #FFB9B3; border-color: #B71C1C; color: #404040; } .stab.deprecated { background: #F3DFFF; border-color: #7F0087; color: #404040; } .stab.portability { background: #C4ECFF; border-color: #7BA5DB; color: #404040; } diff --git a/src/librustdoc/html/static/themes/light.css b/src/librustdoc/html/static/themes/light.css index 4cf35f64d19..4ae10492ae6 100644 --- a/src/librustdoc/html/static/themes/light.css +++ b/src/librustdoc/html/static/themes/light.css @@ -174,6 +174,10 @@ a { color: #3873AD; } +.stab.internal a { + color: #304FFE; +} + a.test-arrow { color: #f5f5f5; } @@ -200,6 +204,7 @@ a.test-arrow { } .stab.unstable { background: #FFF5D6; border-color: #FFC600; } +.stab.internal { background: #FFB9B3; border-color: #B71C1C; } .stab.deprecated { background: #F3DFFF; border-color: #7F0087; } .stab.portability { background: #C4ECFF; border-color: #7BA5DB; } diff --git a/src/test/rustdoc/deprecated.rs b/src/test/rustdoc/deprecated.rs index 744304a62c2..63447ad1690 100644 --- a/src/test/rustdoc/deprecated.rs +++ b/src/test/rustdoc/deprecated.rs @@ -10,7 +10,29 @@ #![feature(deprecated)] +// @matches deprecated/index.html '//*[@class="docblock-short"]' \ +// '^\[Deprecated\] Deprecated docs' // @has deprecated/struct.S.html '//*[@class="stab deprecated"]' \ // 'Deprecated since 1.0.0: text' +/// Deprecated docs #[deprecated(since = "1.0.0", note = "text")] pub struct S; + +// @matches deprecated/index.html '//*[@class="docblock-short"]' '^Docs' +/// Docs +pub struct T; + +// @matches deprecated/struct.U.html '//*[@class="stab deprecated"]' \ +// 'Deprecated since 1.0.0$' +#[deprecated(since = "1.0.0")] +pub struct U; + +// @matches deprecated/struct.V.html '//*[@class="stab deprecated"]' \ +// 'Deprecated: text$' +#[deprecated(note = "text")] +pub struct V; + +// @matches deprecated/struct.W.html '//*[@class="stab deprecated"]' \ +// 'Deprecated$' +#[deprecated] +pub struct W; diff --git a/src/test/rustdoc/internal.rs b/src/test/rustdoc/internal.rs new file mode 100644 index 00000000000..ba58da138a8 --- /dev/null +++ b/src/test/rustdoc/internal.rs @@ -0,0 +1,10 @@ +// compile-flags: -Z force-unstable-if-unmarked + +// @matches internal/index.html '//*[@class="docblock-short"]' \ +// '^\[Internal\] Docs' +// @has internal/struct.S.html '//*[@class="stab internal"]' \ +// 'This is an internal compiler API. (rustc_private)' +/// Docs +pub struct S; + +fn main() {} diff --git a/src/test/rustdoc/issue-27759.rs b/src/test/rustdoc/issue-27759.rs index e82e93230aa..4723b04a078 100644 --- a/src/test/rustdoc/issue-27759.rs +++ b/src/test/rustdoc/issue-27759.rs @@ -14,13 +14,11 @@ #![unstable(feature="test", issue="27759")] // @has issue_27759/unstable/index.html -// @has - '<code>test </code>' -// @has - '<a href="http://issue_url/27759">#27759</a>' +// @has - '<code>test</code> <a href="http://issue_url/27759">#27759</a>' #[unstable(feature="test", issue="27759")] pub mod unstable { // @has issue_27759/unstable/fn.issue.html - // @has - '<code>test_function </code>' - // @has - '<a href="http://issue_url/1234567890">#1234567890</a>' - #[unstable(feature="test_function", issue="1234567890")] + // @has - '<code>test_function</code> <a href="http://issue_url/12345">#12345</a>' + #[unstable(feature="test_function", issue="12345")] pub fn issue() {} } diff --git a/src/test/rustdoc/issue-32374.rs b/src/test/rustdoc/issue-32374.rs index 6d1f8bc1cf9..34423d0176d 100644 --- a/src/test/rustdoc/issue-32374.rs +++ b/src/test/rustdoc/issue-32374.rs @@ -13,15 +13,15 @@ #![unstable(feature="test", issue = "32374")] -// @has issue_32374/index.html '//*[@class="docblock-short"]' \ -// '[Deprecated] [Experimental]' +// @matches issue_32374/index.html '//*[@class="docblock-short"]' \ +// '^\[Deprecated\] \[Experimental\] Docs' // @has issue_32374/struct.T.html '//*[@class="stab deprecated"]' \ // 'Deprecated since 1.0.0: text' -// @has - '<code>test </code>' -// @has - '<a href="http://issue_url/32374">#32374</a>' +// @has - '<code>test</code> <a href="http://issue_url/32374">#32374</a>' // @matches issue_32374/struct.T.html '//*[@class="stab unstable"]' \ -// '🔬 This is a nightly-only experimental API. \(test #32374\)$' +// '🔬 This is a nightly-only experimental API. \(test #32374\)$' +/// Docs #[rustc_deprecated(since = "1.0.0", reason = "text")] #[unstable(feature = "test", issue = "32374")] pub struct T; |