Rustdoc: Format constant values as rich-text and visibility-awarely

[fmease]

In rustdoc, we now attempt to display arbitrary constant values (e.g. structs, arrays). However, we do so intelligently by not showing private or #[doc(hidden)] fields and by creating hyperlinks to the definitions of structs, enums, enum variants, and struct & variant fields. Further, we won't show overly long arrays and (byte) string literals. Instead, we will display a placeholder.
As an aside, a constant value is an evaluated constant expression.

Fixes #98929.
Fixes #99630.

I expect that the UI changes will need some tweaking over time. Consider them an MVP.

The basic framework of the formatter is borrowed from the pretty-printers pretty_print_const{,value} in rustc_middle.
For now, we only pretty-print rustc_middle::ty::Consts and MIR ConstValues. Valtrees are just displayed as _ as I don't
think they surface in rustdoc at the moment since anonymous constants / constant arguments are not evaluated at the time of this writing (see #82852) and just stored as hir::Exprs.

@rustbot label T-rustdoc A-rustdoc-ui

CC @jsha
r? @GuillaumeGomez

---

You can browse the generated docs of src/test/rustdoc/const-value.rs here (points of major interest: Struct and Protocol).

[rustbot]

Error: Only Rust team members can ping teams.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[rustbot]

Error: Parsing ping command in comment failed: ...'nst-eval~~' | error: expected end of command at >| ' (lacking '...

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[jyn514]

cc @rust-lang/wg-const-eval

[RalfJung]

I pretty much copied & pasted pre-existing pretty-printing code and adapted it to the needs of rustdoc:

Is this necessary? The current const pretty-printing is not the result of a lot of careful design, it's just "good enough" for now. It is barely ever seen by users, so there is little pressure to improve it. Given that the rustdoc one will probably be polished, and is seen much more, I think it'd be great if the code could be shared, so that consts as printed in MIR can be (almost) as nice as what rustdoc does.

[fmease]

Thanks for giving some context. I get where you are coming from and I understand your concern about a potential lack of code sharing / potential code duplication.

I think, however, that rustdoc's version of the pretty-printer is going to heavily diverge from the original one both over the course of this PR and over the general lifetime of rustdoc. Already, there are some parts that drastically differ.

In the beginning, I did indeed copy & paste the printing logic but it was a mere starting point – and the only one I'd argue.
Now, my version does not concern itself in the slightest with faithfully rendering all different sorts of inference variables and placeholders, nor pointers and addresses. It simply outputs _ instead. That'd be pretty useless as a debug format.

I really hope that some of my advancements will flow back into the original pretty-printer. Although most of the polishing you speak of will be very specific to rustdoc. Right now it consists of hiding private and hidden fields, hyperlink anchors and ellipses for long arrays and strings. I am not sure whether they fit your use case but I'd be happy to be corrected :)

[GuillaumeGomez]

Overall it's really great! I didn't review too much into the details since we need to have everyone on board with this change but I'm really hopeful about this.

cc @rust-lang/rustdoc

[RalfJung]

@fmease that does sound reasonable; I wanted to make sure you thought about this. :) Would be good to ensure the PR description reflects the final reaosning when the PR lands (as that will be embedded in the git history, too). I'm not familiar enough with the code to really make any concrete suggestions here. Let's see if @oli-obk has any ideas.

[rustbot]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid

[bors]

☔ The latest upstream changes (presumably #100063) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

I think the current version is a great improvement. I expect some UI fixes to follow but we can see that later.

@RalfJung @oli-obk: Is it ok for you to approve this PR?

[bors]

☔ The latest upstream changes (presumably #100318) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #100346) made this pull request unmergeable. Please resolve the merge conflicts.

[RalfJung]

This is not changing the const-eval interpreter or its const representation in any way, and presumably uses the existing APIs in much the same way as the existing pretty-printer, so I don't think there is much I can contribute here in terms of reviewing -- unless you have questions about specific const-eval / interpreter APIs.

So, I leave the decision here up to the primary maintainers of the rustdoc crate.

@lcnr and @oli-obk know better than me what is planned for const representation and valtrees, which affect this much more than my own work on the interpreter internals.

[GuillaumeGomez]

Let's wait to see if one of the two has something to add then. :)

[lcnr]

my current goal would result in constants in patterns always being fully opaque using PartialEq and for us to not support partial valtrees. Not sure if that's possible, haven't had a lot of time for this recently.

This means that to print associated constants, you will have to continue using the ctfe representation as they might not be representable using valtrees. Constants in the type system, i.e. array lengths or arguments for const parameters, will all be representable using valtrees but the compiler has to be able to convert them back to the ctfe representation anyways as they might be used as values by const eval.

I think printing mir constants for rustdoc isn't great, but it seems unavoidable if you want to print associated consts. Also using that routine for type system consts is better than having two routines, one for valtrees and one for associated consts.

The approach therefore feels appropriate to me as long as the rustdoc team has to capacity to maintain this printing routine.

[GuillaumeGomez]

Ok, thanks for approving it. This is now something we need to discuss with @fmease and the other rustdoc team members then.

[bors]

☔ The latest upstream changes (presumably #100511) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #100595) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

So we already have two approvals from here. The discussion on zulip seems stalled so do you think it's okay to merge this as a first step @rust-lang/rustdoc ?

[fmease]

This PR is currently blocked by an RFC I am in the process of writing as per Zulip discussion.

@rustbot blocked

[fmease]

I don't think it makes sense to keep this PR open, it's too bit-rotten. Further, this feature won't land as is anyway but hopefully as part of a more general and flexible mechanism dubbed #[doc(const_display)]. See Zulip topic.