Skip to content

rustdoc: Fix a few issues with associated consts #42865

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 1 commit into from
Jun 25, 2017
Merged

rustdoc: Fix a few issues with associated consts #42865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
66 changes: 26 additions & 40 deletions src/librustdoc/html/render.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1628,55 +1628,47 @@ fn plain_summary_line(s: Option<&str>) -> String {

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

fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink,
render_type: RenderType) -> fmt::Result {
render_type: RenderType, prefix: &str) -> fmt::Result {
if let Some(s) = item.doc_value() {
let markdown = if s.contains('\n') {
format!("{} [Read more]({})",
&plain_summary_line(Some(s)), naive_assoc_href(item, link))
} else {
format!("{}", &plain_summary_line(Some(s)))
};
write!(w, "<div class='docblock'>{}</div>",
Markdown(&markdown, render_type))?;
write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(&markdown, render_type))?;
} else if !prefix.is_empty() {
write!(w, "<div class='docblock'>{}</div>", prefix)?;
}
Ok(())
}

fn md_render_assoc_item(item: &clean::Item) -> String {
fn render_assoc_const_value(item: &clean::Item) -> String {
match item.inner {
clean::AssociatedConstItem(ref ty, ref default) => {
if let Some(default) = default.as_ref() {
format!("```\n{}: {:#} = {}\n```\n\n", item.name.as_ref().unwrap(), ty, default)
} else {
format!("```\n{}: {:#}\n```\n\n", item.name.as_ref().unwrap(), ty)
}
clean::AssociatedConstItem(ref ty, Some(ref default)) => {
highlight::render_with_highlighting(
&format!("{}: {:#} = {}", item.name.as_ref().unwrap(), ty, default),
None,
None,
None,
)
}
_ => String::new(),
}
}

fn get_doc_value(item: &clean::Item) -> Option<&str> {
let x = item.doc_value();
if x.is_none() {
match item.inner {
clean::AssociatedConstItem(_, _) => Some(""),
_ => None,
}
} else {
x
}
}

fn document_full(w: &mut fmt::Formatter, item: &clean::Item,
render_type: RenderType) -> fmt::Result {
if let Some(s) = get_doc_value(item) {
write!(w, "<div class='docblock'>{}</div>",
Markdown(&format!("{}{}", md_render_assoc_item(item), s), render_type))?;
render_type: RenderType, prefix: &str) -> fmt::Result {
if let Some(s) = item.doc_value() {
write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(s, render_type))?;
} else if !prefix.is_empty() {
write!(w, "<div class='docblock'>{}</div>", prefix)?;
}
Ok(())
}
Expand Down Expand Up @@ -2960,14 +2952,6 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
assoc_const(w, item, ty, default.as_ref(), link.anchor(&id))?;
write!(w, "</code></span></h4>\n")?;
}
clean::ConstantItem(ref c) => {
let id = derive_id(format!("{}.{}", item_type, name));
let ns_id = derive_id(format!("{}.{}", name, item_type.name_space()));
write!(w, "<h4 id='{}' class=\"{}\">", id, item_type)?;
write!(w, "<span id='{}' class='invisible'><code>", ns_id)?;
assoc_const(w, item, &c.type_, Some(&c.expr), link.anchor(&id))?;
write!(w, "</code></span></h4>\n")?;
}
clean::AssociatedTypeItem(ref bounds, ref default) => {
let id = derive_id(format!("{}.{}", item_type, name));
let ns_id = derive_id(format!("{}.{}", name, item_type.name_space()));
Expand All @@ -2981,6 +2965,7 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
}

if render_method_item || render_mode == RenderMode::Normal {
let prefix = render_assoc_const_value(item);
if !is_default_item {
if let Some(t) = trait_ {
// The trait item may have been stripped so we might not
Expand All @@ -2989,20 +2974,21 @@ fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLi
// We need the stability of the item from the trait
// because impls can't have a stability.
document_stability(w, cx, it)?;
if get_doc_value(item).is_some() {
document_full(w, item, cx.render_type)?;
if item.doc_value().is_some() {
document_full(w, item, cx.render_type, &prefix)?;
} else {
// In case the item isn't documented,
// provide short documentation from the trait.
document_short(w, it, link, cx.render_type)?;
document_short(w, it, link, cx.render_type, &prefix)?;
}
}
} else {
document(w, cx, item)?;
document_stability(w, cx, item)?;
document_full(w, item, cx.render_type, &prefix)?;
}
} else {
document_stability(w, cx, item)?;
document_short(w, item, link, cx.render_type)?;
document_short(w, item, link, cx.render_type, &prefix)?;
}
}
Ok(())
Expand Down
6 changes: 3 additions & 3 deletions src/librustdoc/passes/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,8 @@ impl<'a> fold::DocFolder for Stripper<'a> {
clean::TraitItem(..) | clean::FunctionItem(..) |
clean::VariantItem(..) | clean::MethodItem(..) |
clean::ForeignFunctionItem(..) | clean::ForeignStaticItem(..) |
clean::ConstantItem(..) | clean::UnionItem(..) => {
clean::ConstantItem(..) | clean::UnionItem(..) |
clean::AssociatedConstItem(..) => {
if i.def_id.is_local() {
if !self.access_levels.is_exported(i.def_id) {
return None;
Expand Down Expand Up @@ -117,8 +118,7 @@ impl<'a> fold::DocFolder for Stripper<'a> {
// Primitives are never stripped
clean::PrimitiveItem(..) => {}

// Associated consts and types are never stripped
clean::AssociatedConstItem(..) |
// Associated types are never stripped
clean::AssociatedTypeItem(..) => {}
}

Expand Down
79 changes: 79 additions & 0 deletions src/test/rustdoc/assoc-consts.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,28 @@ pub trait Foo {
// @has - '//*[@id="associatedconstant.FOO"]' 'const FOO: usize'
// @has - '//*[@class="docblock"]' 'FOO: usize = 12'
const FOO: usize = 12;
// @has - '//*[@id="associatedconstant.FOO_NO_DEFAULT"]' 'const FOO_NO_DEFAULT: bool'
const FOO_NO_DEFAULT: bool;
// @!has - FOO_HIDDEN
#[doc(hidden)]
const FOO_HIDDEN: u8 = 0;
}

pub struct Bar;

impl Foo for Bar {
// @has assoc_consts/struct.Bar.html '//code' 'impl Foo for Bar'
// @has - '//*[@id="associatedconstant.FOO"]' 'const FOO: usize'
// @has - '//*[@class="docblock"]' 'FOO: usize = 12'
const FOO: usize = 12;
// @has - '//*[@id="associatedconstant.FOO_NO_DEFAULT"]' 'const FOO_NO_DEFAULT: bool'
// @has - '//*[@class="docblock"]' 'FOO_NO_DEFAULT: bool = false'
const FOO_NO_DEFAULT: bool = false;
// @!has - FOO_HIDDEN
#[doc(hidden)]
const FOO_HIDDEN: u8 = 0;
}

impl Bar {
// @has assoc_consts/struct.Bar.html '//*[@id="associatedconstant.BAR"]' \
// 'const BAR: usize'
Expand All @@ -44,3 +62,64 @@ impl Bar {
// @has - '//*[@class="docblock"]' "F: fn(_: &(ToString + 'static)) = f"
pub const F: fn(_: &(ToString + 'static)) = f;
}

impl Bar {
// @!has assoc_consts/struct.Bar.html 'BAR_PRIVATE'
const BAR_PRIVATE: char = 'a';
// @!has assoc_consts/struct.Bar.html 'BAR_HIDDEN'
#[doc(hidden)]
pub const BAR_HIDDEN: &'static str = "a";
}

// @has assoc_consts/trait.Qux.html
pub trait Qux {
// @has - '//*[@id="associatedconstant.QUX0"]' 'const QUX0: u8'
// @has - '//*[@class="docblock"]' "Docs for QUX0 in trait."
/// Docs for QUX0 in trait.
const QUX0: u8;
// @has - '//*[@id="associatedconstant.QUX1"]' 'const QUX1: i8'
// @has - '//*[@class="docblock"]' "Docs for QUX1 in trait."
/// Docs for QUX1 in trait.
const QUX1: i8;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT0"]' 'const QUX_DEFAULT0: u16'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT0: u16 = 1"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT0 in trait."
/// Docs for QUX_DEFAULT0 in trait.
const QUX_DEFAULT0: u16 = 1;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT1"]' 'const QUX_DEFAULT1: i16'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT1: i16 = 2"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT1 in trait."
/// Docs for QUX_DEFAULT1 in trait.
const QUX_DEFAULT1: i16 = 2;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT2"]' 'const QUX_DEFAULT2: u32'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT2: u32 = 3"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT2 in trait."
/// Docs for QUX_DEFAULT2 in trait.
const QUX_DEFAULT2: u32 = 3;
}

// @has assoc_consts/struct.Bar.html '//code' 'impl Qux for Bar'
impl Qux for Bar {
// @has - '//*[@id="associatedconstant.QUX0"]' 'const QUX0: u8'
// @has - '//*[@class="docblock"]' "QUX0: u8 = 4"
// @has - '//*[@class="docblock"]' "Docs for QUX0 in trait."
/// Docs for QUX0 in trait.
const QUX0: u8 = 4;
// @has - '//*[@id="associatedconstant.QUX1"]' 'const QUX1: i8'
// @has - '//*[@class="docblock"]' "QUX1: i8 = 5"
// @has - '//*[@class="docblock"]' "Docs for QUX1 in impl."
/// Docs for QUX1 in impl.
const QUX1: i8 = 5;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT0"]' 'const QUX_DEFAULT0: u16'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT0: u16 = 6"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT0 in trait."
const QUX_DEFAULT0: u16 = 6;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT1"]' 'const QUX_DEFAULT1: i16'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT1: i16 = 7"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT1 in impl."
/// Docs for QUX_DEFAULT1 in impl.
const QUX_DEFAULT1: i16 = 7;
// @has - '//*[@id="associatedconstant.QUX_DEFAULT2"]' 'const QUX_DEFAULT2: u32'
// @has - '//*[@class="docblock"]' "QUX_DEFAULT2: u32 = 3"
// @has - '//*[@class="docblock"]' "Docs for QUX_DEFAULT2 in trait."
}