Skip to content

Commit

Permalink
Don't hardcode Id for root (#2)
Browse files Browse the repository at this point in the history
The Json ID's are opaque, and may be changed at any point (In fact, I;m: To quote the [rfc](https://rust-lang.github.io/rfcs/2963-rustdoc-json.html#id):

> They happen to be the compiler internal DefId for that item, but in the JSON blob they should be treated as opaque as they aren't guaranteed to be stable across compiler invocations.

In fact, Its possible rustdoc should mangle `Id`s, so they dont look human readable, because they arn't indended to convey any information themself.

Also: Thanks for writing this post, and I'm super glad to see people finding uses for rustdoc-json. Please file issues if you run into anything or can think of improvements to the json format.
  • Loading branch information
aDotInTheVoid authored Dec 8, 2021
1 parent 6fa511f commit 52f9271
Showing 1 changed file with 11 additions and 9 deletions.
20 changes: 11 additions & 9 deletions content/abcr-issue-0.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
+++
title = "A better cargo-readme - Issue 0: Humble Beginning"
date = 2021-12-06
updated = 2021-12-08
+++

# Introduction
Expand Down Expand Up @@ -205,19 +206,16 @@ The JSON document follows a specific structure defined in the `rustdoc_json_type

## Extracting the crate-level documentation

After a few minutes of diving in the data structures, we can see that all the items that are reachable from the crate are located in the [`index`] field. This field is a JSON dictionary whose keys are the compiler-generated [`DefId`] and values are metadata of the reachable items. Looking at the documentation of the [`def_id`] module tells us that we should look at the crate id 0. After some researches, it turns out that the crate-level documentation are available at for the [`DefId`] "0:0".

I think that the second 0 comes from the order in which the different items of a crate are lowered by Rustc, but that's another story.
After a few minutes of diving in the data structures, we can see that all the items that are reachable from the crate are located in the [`index`] field. This field is a JSON dictionary whose keys are compiler-generated [`Id`]s and values are metadata of the reachable items. Additionally, there is a [`root`] field, which tells us which key in the index map will give us the documentation for the crate's root module.

Let's try to write a command which extracts the crate-level documentation using `jq`:


[`Id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Id.html
[`root`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Crate.html#structfield.root
[`index`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Crate.html#structfield.index
[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html
[`def_id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/index.html

```
$ cat target/doc/abcr_step0.json | jq '{ docs: .index."0:0".docs }'
$ cat target/doc/abcr_step0.json | jq '{docs: .index[.root].docs}'
{
"docs": "# My crate\n\nThe [`Cow`] says moo 🐮\n\n```TOML\n[dependencies]\nabcr_step0 = \"0.1.0\"\n```\n\nHere's some crate-level documentation"
}
Expand All @@ -233,7 +231,7 @@ We did it! We managed to extract the crate documentation from the rustdoc-genera
[`links`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Item.html#structfield.links

```
$ cat target/doc/abcr_step0.json | jq '{ docs: .index."0:0".docs, links: .index."0:0".links }'
$ cat target/doc/abcr_step0.json | jq '{ docs: .index[.root].docs, links: .index[.root].links }'
{
"docs": "# My crate\n\n```TOML\n[dependencies]\nabcr_step0 = \"0.1.0\"\n```\n\nHere's some crate-level documentation\n\nHere's a link to [`Cow`].",
"links": {
Expand All @@ -242,7 +240,7 @@ $ cat target/doc/abcr_step0.json | jq '{ docs: .index."0:0".docs, links: .index.
}
```

This returns the [`DefId`] of the [`Item`] that is linked. Let's see if we can retrieve its path:
This returns the [`Id`] of the [`Item`] that is linked. Let's see if we can retrieve its path:

```
$ cat target/doc/abcr_step0.json | jq '{ links_to_cow: .paths."5:546".path }'
Expand Down Expand Up @@ -271,4 +269,8 @@ This issue was reviewed by volunteers who gave me a lot of feedback. They are, i
- [Natsukoh](https://twitter.com/natsukoow),
- [Yozhgoor 🦀](https://twitter.com/yozhgoor).

Initial release of the blogpost used a hardcoded `id` to retrieve the crate-level documentation. [@aDotInTheVoid] suggested to use the `root` field instead. Thanks!

[@aDotInTheVoid]: https://github.com/aDotInTheVoid

If you're interested in reviewing the next articles or implementation, don't hesitate to message me on Twitter. I gladly welcome any kind of constructive feedback.

0 comments on commit 52f9271

Please sign in to comment.