Stream: rustdoc

Topic: JSON Tracking


view this post on Zulip CraftSpider (May 08 2021 at 02:12):

For the JSON tracking issue (#76578), I think 'Make the changes to the format suggested in #75114 (review)' is good enough to be checked, as all the changes have either been made or we've decided against, aside from possibly making some stuff a list instead of int-to-item map. Would people be okay with me checking it off? (@Joshua Nelson)

view this post on Zulip Joshua Nelson (May 08 2021 at 11:36):

I won't have time to look into it for the next week or so.

view this post on Zulip Stu (May 08 2021 at 17:00):

Speaking of rustdoc-json, what needs to be done to get closer to stabilization? Of course all the bugs/ICEs must be fixed, but except that?

view this post on Zulip Joshua Nelson (May 08 2021 at 18:47):

That's basically what this thread is I think

view this post on Zulip Joshua Nelson (May 08 2021 at 18:48):

I don't have time to look into whether the format is what we want right now

view this post on Zulip Stu (May 08 2021 at 18:54):

Alright. I want to start fixing some bugs in the JSON renderer and help to get it forward because I would love to have this stabilized at some time

view this post on Zulip CraftSpider (May 09 2021 at 02:50):

We still have a checkbox to determine if changes need to be made from use, so I think we should look for at least a handful of people to write things on top of it, from which we can ask them about 'pain points' of the format. I know HeroicKatora has been using it, but I'm not sure if there are yet more.

view this post on Zulip Noah Lev (May 09 2021 at 03:11):

I do feel a bit concerned about exposing too much of rustdoc's internals in a stable public API. Has that been thought about so far?

view this post on Zulip Joshua Nelson (May 09 2021 at 03:20):

@Camelid what part of this do you see as internals? the whole point of rustdoc-json-types is that it should be stable and doesn't have a dependency on librustdoc

view this post on Zulip Joshua Nelson (May 09 2021 at 03:20):

(if your response is "this is just a lot of info", I don't know if that's really useful to consider, the only alternative is "don't have a JSON backend" which there was already an RFC about)

view this post on Zulip Noah Lev (May 09 2021 at 20:09):

Well, one thing is that rustdoc_json_types includes unstable items like trait aliases. If trait aliases change significantly or are removed, would we have to make a breaking change to rustdoc_json_types?

view this post on Zulip Noah Lev (May 09 2021 at 20:15):

I think I just feel worried that it will make refactoring clean harder since it does expose a lot of information.

view this post on Zulip GuillaumeGomez (May 09 2021 at 20:16):

For that I'd prefer us to be done with the cleanup before talking about stabilizing the JSON format. We have too many things going on at the same time so I'd prefer that the stabilization discussion comes when things have settle down a bit.

view this post on Zulip GuillaumeGomez (May 09 2021 at 20:17):

(because stabilizing something as big as the JSON format in rustdoc is actually quite a big topic so I prefer for everyone to be fully available)

view this post on Zulip Noah Lev (May 09 2021 at 20:18):

For that I'd prefer us to be done with the cleanup before talking about stabilizing the JSON format.

I'm not sure if we'll ever be "done" with the cleanup though; it's a continuous process.

view this post on Zulip Noah Lev (May 09 2021 at 20:25):

E.g., fixing bugs in HRTB rendering may require introducing a new clean type that might be a breaking change to rustdoc-json.

view this post on Zulip Joshua Nelson (May 09 2021 at 20:59):

@Camelid hmm it's a good point - I wonder if we should separate info about stable features from info about unstable ones?

view this post on Zulip Joshua Nelson (May 09 2021 at 20:59):

Not sure how that could work

view this post on Zulip CraftSpider (May 09 2021 at 23:18):

First, probably bad idea: There's a top-level stable/unstable flag, if stable it only includes stable stuff, if unstable it adds unstable stuff. Unstable JSON follows the same 'allowed to break stuff' as rustc unstable. Moving things to stable requires a JSON version bump if it's breaking, otherwise not (Same semver rules as we currently follow for everything).

view this post on Zulip Joshua Nelson (May 10 2021 at 00:13):

E.g., fixing bugs in HRTB rendering may require introducing a new clean type that might be a breaking change to rustdoc-json.

This misunderstands the point I think - clean and rustdoc-json are completely separate. It's ok to add info to clean that's not present in JSON. It's also fine to change the clean AST all around as long as the JSON output is the same.

view this post on Zulip Nixon Enraght-Moony (May 11 2021 at 09:19):

In terms of how close the format is to being ready (baring how we want to model language evolution), we still nead to fix how we deal with names. Eg

mod foo { struct HiddenName; }
pub use foo::HiddenName as Name1;
pub use foo::HiddenName as Name2;

pub fn convert(x: Name1) -> Name2 { x }

This currently ICEs. (And the html output isn't good either, as we generate 2 pages for Name1 and Name2, with no anotation that they are the same


Last updated: Oct 21 2021 at 20:47 UTC