Rustc-dev-guide: Link to internal rustdocs

[Michael-F-Bryan]

When rust-lang/rust-central-station#40 lands we'll have a stable location which contains internal API documentation (i.e. the equivalent of ./x.py doc with crate-docs = true) :tada:

This means when referring to a particular struct or function we'll be able too link to its API docs instead of linking to the original source file and hoping for the best.

Once that PR is merged we'll need to:

• [x] Update the code index to point at the API docs instead of source code
• [x] Emphasise linking to API docs where possible when people are contributing new content
• [x] Update the "contributing" section of the README appropriately (#208)
• [x] Update the "How to build the compiler and run what you built" to mention building docs and where they can be found online?

[rajcspsg]

@Michael-F-Bryan - I'm new to rust. Since I see this is Easy tagged issue shall I take this issue?

[Michael-F-Bryan]

@rajcspsg if you'd like to give it a go that's fine with me, I'm also happy to mentor or answer any questions you encounter while trying to tick this issue off :grin:

We'll need to wait for rust-lang/rust-central-station#40 to be fully merged, but after that it should be relatively straightforward. If you subscribe to that issue, GitHub should send you notifications when it is resolved and you can get started.

[rajcspsg]

@Michael-F-Bryan _ Thanks for mentoring me and I'm happy to take your guidance as I'm new to rust.
While we are waiting for related PR to be merged, could you please provide the file which needs to be updated with details.

[Michael-F-Bryan]

It should mainly be a case of looking for all links to source files in the rust-lang/rust repo and replacing them with links to the corresponding API docs.

The easiest way would be to use a tool like grep or ripgrep and search for anything with https:// and .rs in it.

$ rg -e "https?://[^\s]+\.rs"

src/rustc-driver.md
70:[`rustc_driver`]: https://github.com/rust-lang/rust/tree/master/src/librustc_driver
71:[`CompileState`]: https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs

...

You can see that CompileState is a reference to some struct and the link goes to src/librustc_driver/driver.rs in the rust repo. I believe the internal crate docs will be at https://doc.rust-lang.org/nightly-rustc/, so you'd go there and look for the rustc_driver::CompileState docs, then update the link appropriately.

[mark-i-m]

To clarify, you are looking for links in _this_ repo _to_ the other repo :)

[rajcspsg]

Thanks for the suggestion @mark-i-m @Michael-F-Bryan.

When I searched for here for rustc_driver::CompileState, I end up at stable page documentation of rustc_driver version 1.1.0.

I should have get the nightly documentation link instead of 1.1.0 documentation, correct?

[Michael-F-Bryan]

@rajcspsg yes. That version of the docs looks quite outdated (TyCtxt is still called ctxt for example). I assume they manually uploaded internal docs early on and those old 1.1.0 docs are still on the Rust S3 bucket.

Now we've released 1.25 they'll be able to make progress on merging the rust-lang/rust-central-station#40 PR. ~We may have to wait a couple more days before the new docs are uploaded and we can link to them though.~

EDIT: Looks like the PR was merged :tada:

[mark-i-m]

@rajcspsg IIUC, the new docs should be available tomorrow after the next nightly is released.

[rajcspsg]

Thanks @Michael-F-Bryan @mark-i-m.
I've 2 questions on searching the documentation.

1. I searched for DocContext mentioned in this link using keyword rustdoc::core in DuckDuckGo and get this result. But when I searched for hir::Crate, rustc::hir, rustc::hir::mod etc I didn't get any rust documentation. Are those going to updated with tomorrow documentation release?

2. All the links to chapter return 404 error. For example , the parser in page appendix-code-index.md returns url error. Is it need to be fixed?

[mark-i-m]

I searched for DocContext mentioned in this link using keyword rustdoc::core in DuckDuckGo and get this result. But when I searched for hir::Crate, rustc::hir, rustc::hir::mod etc I didn't get any rust documentation. Are those going to updated with tomorrow documentation release?

Hmm... that link looks pretty outdated too. rust 1.1 was a long time ago. Tomorrow all of the docs should be up (or so I am told). They should look like normal rustdocs and should be hosted at doc.rust-lang.org/nightly/nightly-rustc

So tomorrow (hopefully) you should be able to go to doc.rust-lang.org/nightly/nightly-rustc and just use the normal rustdoc search box to find everything (hopefully).

All the links to chapter return 404 error. For example , the parser in page appendix-code-index.md returns url error. Is it need to be fixed?

Ah, they're all relative links. If you use the hosted version here the links should work. Thanks for pointing this out though.

The intent is for people to view the guide as a book (via that host version). Do you think we should fix the links so that they work on github too? It would be a bit of a tedious piece of work, but it's possible...

[rajcspsg]

@mark-i-m - Sure. I will try to fix 404 errors in github as well. I will wait for a day till document release and will let you know if I need any help.

[mark-i-m]

@rajcspsg It looks like there was a bug, which should (hopefully) be fixed for tomorrow.

[Michael-F-Bryan]

@rajcspsg the documentation is [now live] :tada:

[rajcspsg]

Thanks @Michael-F-Bryan @mark-i-m I will work on this and submit PR.

[rajcspsg]

@Michael-F-Bryan @mark-i-m

I've created PR for this documentation link. But I couldn't find link for below items.
Could you please help me.

| s# | FileName | github Link | line# |
|----|---------------------------|-------------------------------------------------------------------------------------------|-------|
| 1 | const-eval.md | https://github.com/rust-lang/rust/blob/master/src/librustc_mir/interpret/const_eval.rs | 38 |
| 2 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/runtest.rs | 186 |
| 3 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs | 234 |
| 4 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs | 235 |
| 5 | intro.md | https://github.com/rust-lang/rust/tree/master/src/bootstrap/test.rs | 169 |
| 6 | miri.md | https://github.com/rust-lang/rust/blob/master/src/librustc_mir/interpret/const_eval.rs | 115 |
| 7 | miri.md | https://github.com/rust-lang/rust/blob/master/src/librustc_mir/interpret/step.rs | 138 |
| 8 | appendix-stupid-stats.md | https://github.com/rust-lang/rust/tree/master/src/librustc_driver/lib.rs | 114 |
| 9 | traits-lowering-module.md | https://github.com/rust-lang/rust/tree/master/src/test/ui/chalkify/lower_impl.rs | 64 |
| 10 | adding.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs | 166 |
| 11 | adding.md | https://github.com/rust-lang/rust/blob/master/src/test/ui/hello_world/main.rs | 248 |
| 12 | adding.md | https://github.com/rust-lang/rust/blob/master/src/test/ui/transmute/main.rs | 312 |
| 13 | type-checking.md | https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/collect.rs | 42 |
| 14 | method-lookup.md | https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/check/method/probe.rs | 41 |
| 15 | method-lookup.md | https://github.com/rust-lang/rust/blob/master/src/librustc_typeck/check/method/confirm.rs | 42 |

Also, for the missing link as we disccussed here, do I need to update github link or documenation link?

[mark-i-m]

Thanks! Nice job :)

I've created PR for this documentation link. But I couldn't find link for below items.

Hmm... I can't find those either. I asked a followup on https://github.com/rust-lang/rust-central-station/pull/40

Also, for the missing link as we disccussed here, do I need to update github link or documenation link?

Do you mean with respect to these links that you mentioned before?

All the links to chapter return 404 error. For example , the parser in page appendix-code-index.md returns url error. Is it need to be fixed?

These should be links to hosted version of the rustc guide itself. I don't think we were expecting anyone to use the github interface to view the book. I'm not sure if we want to make these links absolute or leave them relative as they are... I opened #109 to deal with that; for now, let's leave them as-is.

[mark-i-m]

Also, I will try to look at the PR soon

[mark-i-m]

Ok, that was fast.

The reason those items you listed are not in the hosted docs is that they are private, whereas rustdoc generates documentation for only public items by default. There is active discussion on generating docs for these private items in https://github.com/rust-lang/rust/issues/29893.

[rajcspsg]

sure Thanks @mark-i-m !!!

[mark-i-m]

@rajcspsg I merged your PR :)

It appears that private modules are now documented, so I think you should be able to find the remaining items. Are you still interested in working on this?

[rajcspsg]

@mark-i-m
Thanks for accepting my PR :)
sure I will work on the pending items tonight and submit PR.
I will should be able to find remaining items in same nightly documentation search as others, correct?

[mark-i-m]

I will should be able to find remaining items in same nightly documentation search as others, correct?

That's right

[rajcspsg]

Hey @mark-i-m

I'm still not able to find documentation for below items.

| s#| FileName | github Link | line# |
|---|---------------------------|-------------------------------------------------------------------------------------------|-------|
| 1 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/runtest.rs | 186 |
| 2 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs | 234 |
| 3 | compiletest.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs | 235 |
| 4 | intro.md | https://github.com/rust-lang/rust/tree/master/src/bootstrap/test.rs | 169 |
| 5 | appendix-stupid-stats.md | https://github.com/rust-lang/rust/tree/master/src/librustc_driver/lib.rs | 114 |
| 6 | traits-lowering-module.md | https://github.com/rust-lang/rust/tree/master/src/test/ui/chalkify/lower_impl.rs | 64 |
| 7 | adding.md | https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs | 166 |
| 8 | adding.md | https://github.com/rust-lang/rust/blob/master/src/test/ui/hello_world/main.rs | 248 |
| 9 | adding.md | https://github.com/rust-lang/rust/blob/master/src/test/ui/transmute/main.rs | 312 |

All of them looks like tests but I don't know how to get its documentation link.

[mark-i-m]

Thanks :)

I think anything in src/tools is not part of the compiler proper, so it will not be documented. Likewise, anything in src/test is a test, rather than part of the compiler itself, so those will not be documented either. I think we can leave these links for now.

For (5), I think we can use the following link: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html

[rajcspsg]

@mark-i-m - I've updated the documentation link for https://github.com/rust-lang/rust/tree/master/src/librustc_driver/lib.rs in the PR.

[rajcspsg]

@mark-i-m @Michael-F-Bryan I think still 2 below items are yet to completed in this issue, correct?
Update the "contributing" section of the README appropriately
Update the "How to build the compiler and run what you built" to mention building docs and where they can be found online?

[mark-i-m]

@rajcspsg Yes, that's correct

[rajcspsg]

@mark-i-m i may need some pointers to start with. What should be updated in contributing section?

[mark-i-m]

Perhaps we can start a "Contributor Tips" section at the end? The first tip can be something like "Whenever referring to a part of the rustc source code, please add a link to the rustc rustdocs. Since these links are checked, it will help us discover when something in the compiler changes and the guide needs to be updated."

[mark-i-m]

@Michael-F-Bryan did you have something specific in mind?

[mark-i-m]

Ping @Michael-F-Bryan ^^^

[Michael-F-Bryan]

Oops, looks like I missed this somehow!

@Michael-F-Bryan did you have something specific in mind?

I was just thinking we should mention in the contributor guide that the internal API docs are available online and to link to them where possible. The comment you made sounds pretty good.

Whenever referring to a part of the rustc source code, please add a link to the rustc rustdocs. Since these links are checked, it will help us discover when something in the compiler changes and the guide needs to be updated.

[mark-i-m]

Ping @rajcspsg Are you still interested in working on this?

[gnzlbg]

I actually have had a lot of trouble looking for the API docs of rustc (are they linked from anywhere? I couldn't easily find it), they should at least be linked in the readme, or have a section somewhere with a link to the docs. FWIW, this is the link: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/

[mark-i-m]

I agree. The docs are surprisingly hard to Google.

[nikomatsakis]

Wow, there are a lot of comments here. I recently opened up https://github.com/rust-lang-nursery/rustc-guide/pull/189, which added links to the rustdoc for the HIR section. I was thinking we should open a fresh issue (this one is perhaps too cluttered) and make it into a "quest issue". Basically, make a checklist of modules that need work, and issue out a call to try to get people involved. Seems like a nice "starter point". But maybe that's not necessary, even?

[rajcspsg]

@nikomatsakis @mark-i-m Hello guys. I'm really sorry that I'm out for a while due to few personal commitments. I think it would be good to open new issue for pending things for this PR.

[mark-i-m]

I'll try to curate such a list and open a new issue sometime soon. I'm not sure if I will have time today, though. I will post back here soon.

[rajcspsg]

@mark-i-m does this PR https://github.com/rust-lang-nursery/rustc-guide/pull/195 covers point 4 this is issue?

[mark-i-m]

Hmm... do we ever mention where they can be found? (https://doc.rust-lang.org/nightly/nightly-rustc/rustc/)

Sorry for the delay on this. I have been pretty swamped for the past few weeks (and will probably continue to be swamped until at least Oct 12)... I appreciate your patience!

[mark-i-m]

Ok, so I opened #209 to track the links @rajcspsg mentioned in https://github.com/rust-lang-nursery/rustc-guide/issues/100#issuecomment-379420709. I'm not really sure how to make progress there TBH, but I don't want to lose the list of links.

I also opened #208 to update the readme, as per the checklist in the OP. @Michael-F-Bryan @rajcspsg let me know what you think.

@rajcspsg I think the only thing left here is to update the intro section of the guide itself with a note and link to the compiler rustdocs.

[rajcspsg]

@mark-i-m shall we mark How to build the compiler and run what you built section done.

[mark-i-m]

Hmm... do we ever mention where they can be found? (https://doc.rust-lang.org/nightly/nightly-rustc/rustc/)

[rajcspsg]

@mark-i-m I will update and send PR for that. I have a question.
Which file I have to update compiler-documenting.md or how-to-build-and-run.md.
Looks to me compiler documenting is correct place?

[mark-i-m]

Perhaps both? compiler-documenting seems like a logical place, but I would also like the link to be highly-visible, since they are really useful.

[mark-i-m]

Hooray! :tada: This is done :smile:

Nice job @rajcspsg! This is a major improvement to the guide!

[rajcspsg]

Thanks @mark-i-m for accepting my PR :)