rustdoc: Fix generating documentation from json

[mitaa]

fixes#25108

r? @alexcrichton

[alexcrichton]

Thanks for the PR @mitaa! I've actually been somewhat wary about fixing this in the past as I'm not sure if we want to actually export a JSON interface to rustdoc. It's likely to be highly brittle, undocumented, and not really suitable for most purposes.

That being said, we should probably either make the decision to fix it or remove it altogether! This seems like as good a place as any to get the conversation started at least.

cc @rust-lang/tools, thoughts on JSON documentation in rustdoc? Perhaps we should just rip it out?

[nrc]

Do we know if anyone uses it? Or wants to use it?

[alexcrichton]

One reason I believe this comes up is that it's so prominently mentioned. The rustdoc -h page indicates that reading/writing json output is supported, and I suspect that some just try that out, see it doesn't work, and then submit a bug.

[brson]

I'm in favor of just removing it. If somebody wants to produce better docs they will probably just write rustdoc 3.

[brson]

cc @cmr

[emberian]

And thus the cycle repeats. All this has happened before, and all of it will happen again.

On April 6, 2016 7:16:02 AM GMT+10:00, Brian Anderson notifications@github.com wrote:

I'm in favor of just removing it. If somebody wants to produce better
docs they will probably just write rustdoc 3.

---

You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub:
#32698 (comment)

Sent from my Android device with K-9 Mail. Please excuse my brevity.

[alexcrichton]

We discussed this in the tools triage meeting today and the conclusion was that we probably just want to jettison this support for now. We can perhaps add it back later if need be but for now it's unstable enough and likely hasn't ever worked that it shouldn't break anything and we probably don't want to stabilize it.

Would you be ok preparing a PR for that @mitaa?

[mitaa]

Sure!

[UtherII]

Personally i planned to use it as a base to see if I could make a better looking documentation, but the generated json is pretty complex anyway. I will look if i can make rustdoc generate clean xml.

[alexcrichton]

@UtherII yeah that was the theoretical purpose of the JSON, but 60% of the work in rustdoc is just taking this JSON and render it, so it wouldn't be an easy task adding an entirely new frontend unfortunately :(