Skip to content

Commit

Permalink
Show value for consts in the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
ohadravid committed Dec 24, 2019
1 parent 6253754 commit 811bdee
Show file tree
Hide file tree
Showing 11 changed files with 192 additions and 16 deletions.
1 change: 1 addition & 0 deletions Cargo.lock
Original file line number Diff line number Diff line change
Expand Up @@ -3869,6 +3869,7 @@ dependencies = [
name = "rustdoc"
version = "0.0.0"
dependencies = [
"itertools 0.8.0",
"minifier",
"pulldown-cmark 0.5.3",
"rustc-rayon",
Expand Down
2 changes: 1 addition & 1 deletion src/libcore/num/f32.rs
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ pub const DIGITS: u32 = 6;
///
/// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
#[stable(feature = "rust1", since = "1.0.0")]
pub const EPSILON: f32 = 1.19209290e-07_f32;
pub const EPSILON: f32 = 1.1920929e-7_f32;

/// Smallest finite `f32` value.
#[stable(feature = "rust1", since = "1.0.0")]
Expand Down
1 change: 1 addition & 0 deletions src/librustdoc/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,4 @@ rayon = { version = "0.3.0", package = "rustc-rayon" }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tempfile = "3"
itertools = "0.8"
11 changes: 10 additions & 1 deletion src/librustdoc/clean/inline.rs
Original file line number Diff line number Diff line change
Expand Up @@ -450,7 +450,16 @@ pub fn print_inlined_const(cx: &DocContext<'_>, did: DefId) -> String {
}

fn build_const(cx: &DocContext<'_>, did: DefId) -> clean::Constant {
clean::Constant { type_: cx.tcx.type_of(did).clean(cx), expr: print_inlined_const(cx, did) }
clean::Constant {
type_: cx.tcx.type_of(did).clean(cx),
expr: print_inlined_const(cx, did),
value: clean::utils::print_evaluated_const(cx, did),
is_literal: cx
.tcx
.hir()
.as_local_hir_id(did)
.map_or(false, |hir_id| clean::utils::is_literal_expr(cx, hir_id)),
}
}

fn build_static(cx: &DocContext<'_>, did: DefId, mutable: bool) -> clean::Static {
Expand Down
15 changes: 13 additions & 2 deletions src/librustdoc/clean/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,8 @@ impl Clean<Constant> for hir::ConstArg {
Constant {
type_: cx.tcx.type_of(cx.tcx.hir().body_owner_def_id(self.value.body)).clean(cx),
expr: print_const_expr(cx, self.value.body),
value: None,
is_literal: is_literal_expr(cx, self.value.body.hir_id),
}
}
}
Expand Down Expand Up @@ -1717,7 +1719,12 @@ impl<'tcx> Clean<Type> for Ty<'tcx> {

impl<'tcx> Clean<Constant> for ty::Const<'tcx> {
fn clean(&self, cx: &DocContext<'_>) -> Constant {
Constant { type_: self.ty.clean(cx), expr: format!("{}", self) }
Constant {
type_: self.ty.clean(cx),
expr: format!("{}", self),
value: None,
is_literal: false,
}
}
}

Expand Down Expand Up @@ -2062,17 +2069,21 @@ impl Clean<Item> for doctree::Static<'_> {

impl Clean<Item> for doctree::Constant<'_> {
fn clean(&self, cx: &DocContext<'_>) -> Item {
let def_id = cx.tcx.hir().local_def_id(self.id);

Item {
name: Some(self.name.clean(cx)),
attrs: self.attrs.clean(cx),
source: self.whence.clean(cx),
def_id: cx.tcx.hir().local_def_id(self.id),
def_id,
visibility: self.vis.clean(cx),
stability: cx.stability(self.id).clean(cx),
deprecation: cx.deprecation(self.id).clean(cx),
inner: ConstantItem(Constant {
type_: self.type_.clean(cx),
expr: print_const_expr(cx, self.expr),
value: print_evaluated_const(cx, def_id),
is_literal: is_literal_expr(cx, self.expr.hir_id),
}),
}
}
Expand Down
2 changes: 2 additions & 0 deletions src/librustdoc/clean/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1460,6 +1460,8 @@ pub struct Static {
pub struct Constant {
pub type_: Type,
pub expr: String,
pub value: Option<String>,
pub is_literal: bool,
}

#[derive(Clone, PartialEq, Debug)]
Expand Down
77 changes: 74 additions & 3 deletions src/librustdoc/clean/utils.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,18 @@ use crate::clean::{
};
use crate::core::DocContext;

use itertools::Itertools;
use rustc::hir;
use rustc::hir::def::{DefKind, Res};
use rustc::hir::def_id::{DefId, LOCAL_CRATE};
use rustc::mir::interpret::{sign_extend, ConstValue, Scalar};
use rustc::ty::subst::{GenericArgKind, SubstsRef};
use rustc::ty::{self, DefIdTree, Ty};
use rustc::util::nodemap::FxHashSet;
use std::mem;
use syntax_pos;
use syntax_pos::symbol::{kw, sym, Symbol};

use std::mem;

pub fn krate(mut cx: &mut DocContext<'_>) -> Crate {
use crate::visit_lib::LibEmbargoVisitor;

Expand Down Expand Up @@ -482,8 +483,78 @@ pub fn print_const(cx: &DocContext<'_>, n: &ty::Const<'_>) -> String {
}
}

pub fn print_evaluated_const(cx: &DocContext<'_>, def_id: DefId) -> Option<String> {
let value =
cx.tcx.const_eval_poly(def_id).ok().and_then(|value| match (value.val, &value.ty.kind) {
(_, ty::Ref(..)) => None,
(ty::ConstKind::Value(ConstValue::Scalar(_)), ty::Adt(_, _)) => None,
(ty::ConstKind::Value(ConstValue::Scalar(_)), _) => {
Some(print_const_with_custom_print_scalar(cx, value))
}
_ => None,
});

value
}

fn format_integer_with_underscore_sep(num: &str) -> String {
let num_chars: Vec<_> = num.chars().collect();
let num_start_index = if num_chars.get(0) == Some(&'-') { 1 } else { 0 };

num_chars[..num_start_index]
.iter()
.chain(num_chars[num_start_index..].rchunks(3).rev().intersperse(&['_']).flatten())
.collect()
}

fn print_const_with_custom_print_scalar(cx: &DocContext<'_>, ct: &'tcx ty::Const<'tcx>) -> String {
// Use a slightly different format for integer types which always shows the actual value.
// For all other types, fallback to the original `pretty_print_const`.
match (ct.val, &ct.ty.kind) {
(ty::ConstKind::Value(ConstValue::Scalar(Scalar::Raw { data, .. })), ty::Uint(ui)) => {
format!("{}{}", format_integer_with_underscore_sep(&data.to_string()), ui.name_str())
}
(ty::ConstKind::Value(ConstValue::Scalar(Scalar::Raw { data, .. })), ty::Int(i)) => {
let ty = cx.tcx.lift(&ct.ty).unwrap();
let size = cx.tcx.layout_of(ty::ParamEnv::empty().and(ty)).unwrap().size;
let sign_extended_data = sign_extend(data, size) as i128;

format!(
"{}{}",
format_integer_with_underscore_sep(&sign_extended_data.to_string()),
i.name_str()
)
}
_ => ct.to_string(),
}
}

pub fn is_literal_expr(cx: &DocContext<'_>, hir_id: hir::HirId) -> bool {
if let hir::Node::Expr(expr) = cx.tcx.hir().get(hir_id) {
if let hir::ExprKind::Lit(_) = &expr.kind {
return true;
}

if let hir::ExprKind::Unary(hir::UnOp::UnNeg, expr) = &expr.kind {
if let hir::ExprKind::Lit(_) = &expr.kind {
return true;
}
}
}

false
}

pub fn print_const_expr(cx: &DocContext<'_>, body: hir::BodyId) -> String {
cx.tcx.hir().hir_to_pretty_string(body.hir_id)
let value = &cx.tcx.hir().body(body).value;

let snippet = if !value.span.from_expansion() {
cx.sess().source_map().span_to_snippet(value.span).ok()
} else {
None
};

snippet.unwrap_or_else(|| cx.tcx.hir().hir_to_pretty_string(body.hir_id))
}

/// Given a type Path, resolve it to a Type using the TyCtxt
Expand Down
26 changes: 24 additions & 2 deletions src/librustdoc/html/render.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2272,14 +2272,36 @@ fn short_stability(item: &clean::Item, cx: &Context) -> Vec<String> {
fn item_constant(w: &mut Buffer, cx: &Context, it: &clean::Item, c: &clean::Constant) {
write!(w, "<pre class='rust const'>");
render_attributes(w, it, false);

write!(
w,
"{vis}const \
{name}: {typ}</pre>",
{name}: {typ}",
vis = it.visibility.print_with_space(),
name = it.name.as_ref().unwrap(),
typ = c.type_.print()
typ = c.type_.print(),
);

if c.value.is_some() || c.is_literal {
write!(w, " = {expr};", expr = c.expr);
} else {
write!(w, ";");
}

if let Some(value) = &c.value {
if !c.is_literal {
let value_lowercase = value.to_lowercase();
let expr_lowercase = c.expr.to_lowercase();

if value_lowercase != expr_lowercase
&& value_lowercase.trim_end_matches("i32") != expr_lowercase
{
write!(w, " // {value}", value = value);
}
}
}

write!(w, "</pre>");
document(w, cx, it)
}

Expand Down
4 changes: 2 additions & 2 deletions src/test/rustdoc/const-generics/const-impl.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,14 @@ pub struct VSet<T, const ORDER: Order> {
inner: Vec<T>,
}

// @has foo/struct.VSet.html '//h3[@id="impl"]/code' 'impl<T> VSet<T, { Order::Sorted }>'
// @has foo/struct.VSet.html '//h3[@id="impl"]/code' 'impl<T> VSet<T, {Order::Sorted}>'
impl <T> VSet<T, {Order::Sorted}> {
pub fn new() -> Self {
Self { inner: Vec::new() }
}
}

// @has foo/struct.VSet.html '//h3[@id="impl-1"]/code' 'impl<T> VSet<T, { Order::Unsorted }>'
// @has foo/struct.VSet.html '//h3[@id="impl-1"]/code' 'impl<T> VSet<T, {Order::Unsorted}>'
impl <T> VSet<T, {Order::Unsorted}> {
pub fn new() -> Self {
Self { inner: Vec::new() }
Expand Down
5 changes: 0 additions & 5 deletions src/test/rustdoc/dont-show-const-contents.rs

This file was deleted.

64 changes: 64 additions & 0 deletions src/test/rustdoc/show-const-contents.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
// Test that the contents of constants are displayed as part of the
// documentation.

// @has show_const_contents/constant.CONST_S.html 'show this'
// @!has show_const_contents/constant.CONST_S.html '; //'
pub const CONST_S: &'static str = "show this";

// @has show_const_contents/constant.CONST_I32.html '= 42;'
// @!has show_const_contents/constant.CONST_I32.html '; //'
pub const CONST_I32: i32 = 42;

// @has show_const_contents/constant.CONST_I32_HEX.html '= 0x42;'
// @!has show_const_contents/constant.CONST_I32_HEX.html '; //'
pub const CONST_I32_HEX: i32 = 0x42;

// @has show_const_contents/constant.CONST_NEG_I32.html '= -42;'
// @!has show_const_contents/constant.CONST_NEG_I32.html '; //'
pub const CONST_NEG_I32: i32 = -42;

// @has show_const_contents/constant.CONST_EQ_TO_VALUE_I32.html '= 42i32;'
// @!has show_const_contents/constant.CONST_EQ_TO_VALUE_I32.html '// 42i32'
pub const CONST_EQ_TO_VALUE_I32: i32 = 42i32;

// @has show_const_contents/constant.CONST_CALC_I32.html '= 42 + 1; // 43i32'
pub const CONST_CALC_I32: i32 = 42 + 1;

// @!has show_const_contents/constant.CONST_REF_I32.html '= &42;'
// @!has show_const_contents/constant.CONST_REF_I32.html '; //'
pub const CONST_REF_I32: &'static i32 = &42;

// @has show_const_contents/constant.CONST_I32_MAX.html '= i32::max_value(); // 2_147_483_647i32'
pub const CONST_I32_MAX: i32 = i32::max_value();

// @!has show_const_contents/constant.UNIT.html '= ();'
// @!has show_const_contents/constant.UNIT.html '; //'
pub const UNIT: () = ();

pub struct MyType(i32);

// @!has show_const_contents/constant.MY_TYPE.html '= MyType(42);'
// @!has show_const_contents/constant.MY_TYPE.html '; //'
pub const MY_TYPE: MyType = MyType(42);

pub struct MyTypeWithStr(&'static str);

// @!has show_const_contents/constant.MY_TYPE_WITH_STR.html '= MyTypeWithStr("show this");'
// @!has show_const_contents/constant.MY_TYPE_WITH_STR.html '; //'
pub const MY_TYPE_WITH_STR: MyTypeWithStr = MyTypeWithStr("show this");

// @has show_const_contents/constant.EPSILON.html '1.1920929e-7f32;'
// @!has show_const_contents/constant.EPSILON.html '; //'
pub use std::f32::EPSILON;

// @has show_const_contents/constant.MAX.html '= i32::max_value(); // 2_147_483_647i32'
pub use std::i32::MAX;

macro_rules! int_module {
($T:ident) => (
pub const MIN: $T = $T::min_value();
)
}

// @has show_const_contents/constant.MIN.html '= i16::min_value(); // -32_768i16'
int_module!(i16);

0 comments on commit 811bdee

Please sign in to comment.