Skip to content

Commit fc9ccfd

Browse files
borsbors
committed
Auto merge of rust-lang#42865 - ollie27:rustdoc_assoc_consts, r=GuillaumeGomez
rustdoc: Fix a few issues with associated consts * Make sure private consts are stripped. * Don't show a code block for the value if there is none. * Make sure default values are shown in impls. * Make sure docs from the trait are used if the impl has no docs.
2 parents bc9822a + 4488f9b commit fc9ccfd

File tree

3 files changed

+108
-43
lines changed

3 files changed

+108
-43
lines changed

‎src/librustdoc/html/render.rs

+26-40
Original file line numberDiff line numberDiff line change
@@ -1628,55 +1628,47 @@ fn plain_summary_line(s: Option<&str>) -> String {
16281628

16291629
fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Result {
16301630
document_stability(w, cx, item)?;
1631-
document_full(w, item, cx.render_type)?;
1631+
let prefix = render_assoc_const_value(item);
1632+
document_full(w, item, cx.render_type, &prefix)?;
16321633
Ok(())
16331634
}
16341635

16351636
fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink,
1636-
render_type: RenderType) -> fmt::Result {
1637+
render_type: RenderType, prefix: &str) -> fmt::Result {
16371638
if let Some(s) = item.doc_value() {
16381639
let markdown = if s.contains('\n') {
16391640
format!("{} [Read more]({})",
16401641
&plain_summary_line(Some(s)), naive_assoc_href(item, link))
16411642
} else {
16421643
format!("{}", &plain_summary_line(Some(s)))
16431644
};
1644-
write!(w, "<div class='docblock'>{}</div>",
1645-
Markdown(&markdown, render_type))?;
1645+
write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(&markdown, render_type))?;
1646+
} else if !prefix.is_empty() {
1647+
write!(w, "<div class='docblock'>{}</div>", prefix)?;
16461648
}
16471649
Ok(())
16481650
}
16491651

1650-
fn md_render_assoc_item(item: &clean::Item) -> String {
1652+
fn render_assoc_const_value(item: &clean::Item) -> String {
16511653
match item.inner {
1652-
clean::AssociatedConstItem(ref ty, ref default) => {
1653-
if let Some(default) = default.as_ref() {
1654-
format!("```\n{}: {:#} = {}\n```\n\n", item.name.as_ref().unwrap(), ty, default)
1655-
} else {
1656-
format!("```\n{}: {:#}\n```\n\n", item.name.as_ref().unwrap(), ty)
1657-
}
1654+
clean::AssociatedConstItem(ref ty, Some(ref default)) => {
1655+
highlight::render_with_highlighting(
1656+
&format!("{}: {:#} = {}", item.name.as_ref().unwrap(), ty, default),
1657+
None,
1658+
None,
1659+
None,
1660+
)
16581661
}
16591662
_ => String::new(),
16601663
}
16611664
}
16621665

1663-
fn get_doc_value(item: &clean::Item) -> Option<&str> {
1664-
let x = item.doc_value();
1665-
if x.is_none() {
1666-
match item.inner {
1667-
clean::AssociatedConstItem(_, _) => Some(""),
1668-
_ => None,
1669-
}
1670-
} else {
1671-
x
1672-
}
1673-
}
1674-
16751666
fn document_full(w: &mut fmt::Formatter, item: &clean::Item,
1676-
render_type: RenderType) -> fmt::Result {
1677-
if let Some(s) = get_doc_value(item) {
1678-
write!(w, "<div class='docblock'>{}</div>",
1679-
Markdown(&format!("{}{}", md_render_assoc_item(item), s), render_type))?;
1667+
render_type: RenderType, prefix: &str) -> fmt::Result {
1668+
if let Some(s) = item.doc_value() {
1669+
write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(s, render_type))?;
1670+
} else if !prefix.is_empty() {
1671+
write!(w, "<div class='docblock'>{}</div>", prefix)?;
16801672
}
16811673
Ok(())
16821674
}
@@ -2960,14 +2952,6 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
29602952
assoc_const(w, item, ty, default.as_ref(), link.anchor(&id))?;
29612953
write!(w, "</code></span></h4>\n")?;
29622954
}
2963-
clean::ConstantItem(ref c) => {
2964-
let id = derive_id(format!("{}.{}", item_type, name));
2965-
let ns_id = derive_id(format!("{}.{}", name, item_type.name_space()));
2966-
write!(w, "<h4 id='{}' class=\"{}\">", id, item_type)?;
2967-
write!(w, "<span id='{}' class='invisible'><code>", ns_id)?;
2968-
assoc_const(w, item, &c.type_, Some(&c.expr), link.anchor(&id))?;
2969-
write!(w, "</code></span></h4>\n")?;
2970-
}
29712955
clean::AssociatedTypeItem(ref bounds, ref default) => {
29722956
let id = derive_id(format!("{}.{}", item_type, name));
29732957
let ns_id = derive_id(format!("{}.{}", name, item_type.name_space()));
@@ -2981,6 +2965,7 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
29812965
}
29822966

29832967
if render_method_item || render_mode == RenderMode::Normal {
2968+
let prefix = render_assoc_const_value(item);
29842969
if !is_default_item {
29852970
if let Some(t) = trait_ {
29862971
// The trait item may have been stripped so we might not
@@ -2989,20 +2974,21 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
29892974
// We need the stability of the item from the trait
29902975
// because impls can't have a stability.
29912976
document_stability(w, cx, it)?;
2992-
if get_doc_value(item).is_some() {
2993-
document_full(w, item, cx.render_type)?;
2977+
if item.doc_value().is_some() {
2978+
document_full(w, item, cx.render_type, &prefix)?;
29942979
} else {
29952980
// In case the item isn't documented,
29962981
// provide short documentation from the trait.
2997-
document_short(w, it, link, cx.render_type)?;
2982+
document_short(w, it, link, cx.render_type, &prefix)?;
29982983
}
29992984
}
30002985
} else {
3001-
document(w, cx, item)?;
2986+
document_stability(w, cx, item)?;
2987+
document_full(w, item, cx.render_type, &prefix)?;
30022988
}
30032989
} else {
30042990
document_stability(w, cx, item)?;
3005-
document_short(w, item, link, cx.render_type)?;
2991+
document_short(w, item, link, cx.render_type, &prefix)?;
30062992
}
30072993
}
30082994
Ok(())

‎src/librustdoc/passes/mod.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,8 @@ impl<'a> fold::DocFolder for Stripper<'a> {
8383
clean::TraitItem(..) | clean::FunctionItem(..) |
8484
clean::VariantItem(..) | clean::MethodItem(..) |
8585
clean::ForeignFunctionItem(..) | clean::ForeignStaticItem(..) |
86-
clean::ConstantItem(..) | clean::UnionItem(..) => {
86+
clean::ConstantItem(..) | clean::UnionItem(..) |
87+
clean::AssociatedConstItem(..) => {
8788
if i.def_id.is_local() {
8889
if !self.access_levels.is_exported(i.def_id) {
8990
return None;
@@ -117,8 +118,7 @@ impl<'a> fold::DocFolder for Stripper<'a> {
117118
// Primitives are never stripped
118119
clean::PrimitiveItem(..) => {}
119120

120-
// Associated consts and types are never stripped
121-
clean::AssociatedConstItem(..) |
121+
// Associated types are never stripped
122122
clean::AssociatedTypeItem(..) => {}
123123
}
124124

‎src/test/rustdoc/assoc-consts.rs

+79
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,28 @@ pub trait Foo {
1616
// @has - '//*[@id="associatedconstant.FOO"]' 'const FOO: usize'
1717
// @has - '//*[@class="docblock"]' 'FOO: usize = 12'
1818
const FOO: usize = 12;
19+
// @has - '//*[@id="associatedconstant.FOO_NO_DEFAULT"]' 'const FOO_NO_DEFAULT: bool'
20+
const FOO_NO_DEFAULT: bool;
21+
// @!has - FOO_HIDDEN
22+
#[doc(hidden)]
23+
const FOO_HIDDEN: u8 = 0;
1924
}
2025

2126
pub struct Bar;
2227

28+
impl Foo for Bar {
29+
// @has assoc_consts/struct.Bar.html '//code' 'impl Foo for Bar'
30+
// @has - '//*[@id="associatedconstant.FOO"]' 'const FOO: usize'
31+
// @has - '//*[@class="docblock"]' 'FOO: usize = 12'
32+
const FOO: usize = 12;
33+
// @has - '//*[@id="associatedconstant.FOO_NO_DEFAULT"]' 'const FOO_NO_DEFAULT: bool'
34+
// @has - '//*[@class="docblock"]' 'FOO_NO_DEFAULT: bool = false'
35+
const FOO_NO_DEFAULT: bool = false;
36+
// @!has - FOO_HIDDEN
37+
#[doc(hidden)]
38+
const FOO_HIDDEN: u8 = 0;
39+
}
40+
2341
impl Bar {
2442
// @has assoc_consts/struct.Bar.html '//*[@id="associatedconstant.BAR"]' \
2543
// 'const BAR: usize'
@@ -44,3 +62,64 @@ impl Bar {
4462
// @has - '//*[@class="docblock"]' "F: fn(_: &(ToString + 'static)) = f"
4563
pub const F: fn(_: &(ToString + 'static)) = f;
4664
}
65+
66+
impl Bar {
67+
// @!has assoc_consts/struct.Bar.html 'BAR_PRIVATE'
68+
const BAR_PRIVATE: char = 'a';
69+
// @!has assoc_consts/struct.Bar.html 'BAR_HIDDEN'
70+
#[doc(hidden)]
71+
pub const BAR_HIDDEN: &'static str = "a";
72+
}
73+
74+
// @has assoc_consts/trait.Qux.html
75+
pub trait Qux {
76+
// @has - '//*[@id="associatedconstant.QUX0"]' 'const QUX0: u8'
77+
// @has - '//*[@class="docblock"]' "Docs for QUX0 in trait."
78+
/// Docs for QUX0 in trait.
79+
const QUX0: u8;
80+
// @has - '//*[@id="associatedconstant.QUX1"]' 'const QUX1: i8'
81+
// @has - '//*[@class="docblock"]' "Docs for QUX1 in trait."
82+
/// Docs for QUX1 in trait.
83+
const QUX1: i8;
84+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT0"]' 'const QUX_DEFAULT0: u16'
85+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT0: u16 = 1"
86+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT0 in trait."
87+
/// Docs for QUX_DEFAULT0 in trait.
88+
const QUX_DEFAULT0: u16 = 1;
89+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT1"]' 'const QUX_DEFAULT1: i16'
90+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT1: i16 = 2"
91+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT1 in trait."
92+
/// Docs for QUX_DEFAULT1 in trait.
93+
const QUX_DEFAULT1: i16 = 2;
94+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT2"]' 'const QUX_DEFAULT2: u32'
95+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT2: u32 = 3"
96+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT2 in trait."
97+
/// Docs for QUX_DEFAULT2 in trait.
98+
const QUX_DEFAULT2: u32 = 3;
99+
}
100+
101+
// @has assoc_consts/struct.Bar.html '//code' 'impl Qux for Bar'
102+
impl Qux for Bar {
103+
// @has - '//*[@id="associatedconstant.QUX0"]' 'const QUX0: u8'
104+
// @has - '//*[@class="docblock"]' "QUX0: u8 = 4"
105+
// @has - '//*[@class="docblock"]' "Docs for QUX0 in trait."
106+
/// Docs for QUX0 in trait.
107+
const QUX0: u8 = 4;
108+
// @has - '//*[@id="associatedconstant.QUX1"]' 'const QUX1: i8'
109+
// @has - '//*[@class="docblock"]' "QUX1: i8 = 5"
110+
// @has - '//*[@class="docblock"]' "Docs for QUX1 in impl."
111+
/// Docs for QUX1 in impl.
112+
const QUX1: i8 = 5;
113+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT0"]' 'const QUX_DEFAULT0: u16'
114+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT0: u16 = 6"
115+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT0 in trait."
116+
const QUX_DEFAULT0: u16 = 6;
117+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT1"]' 'const QUX_DEFAULT1: i16'
118+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT1: i16 = 7"
119+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT1 in impl."
120+
/// Docs for QUX_DEFAULT1 in impl.
121+
const QUX_DEFAULT1: i16 = 7;
122+
// @has - '//*[@id="associatedconstant.QUX_DEFAULT2"]' 'const QUX_DEFAULT2: u32'
123+
// @has - '//*[@class="docblock"]' "QUX_DEFAULT2: u32 = 3"
124+
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT2 in trait."
125+
}

0 commit comments

Comments
 (0)