frewsxcv · GitHub

Add a notation how to create relative links in documentation comments
(based on Rust item paths) and extend Rustdoc to automatically turn this
into working links.

@frewsxcv added T-doc

Relevant to the documentation team, which will review and decide on the RFC.

T-dev-tools

Relevant to the development tools team, which will review and decide on the RFC.

labels

Mar 7, 2017
- Resolving paths
- Path ambiguities
- Linking to external crates
- Mention this is valid Markdown
- Add more alternatives

@killercup

@nrc nrc mentioned this pull request

Jul 25, 2017

Closed

27 tasks

@nrc

Closed

10 tasks

Open

@Mange Mange mentioned this pull request

Dec 19, 2017

Closed

Merged

12 tasks

bors added a commit to rust-lang/rust that referenced this pull request

Jan 22, 2018
…Gomez,QuietMisdreavus,Manishearth
Implement RFC 1946 - intra-rustdoc links
rust-lang/rfcs#1946 #43466
Note for reviewers: The plain line counts are a little inflated because of how the markdown link parsing was done. [Read the file diff with "whitespace only" changes removed](https://github.com/rust-lang/rust/pull/47046/files?w=1) to get a better view of what actually changed there.
This pulls the name/path resolution mechanisms out of the compiler and runs it on the markdown in a crate's docs, so that links can be made to `SomeStruct` directly rather than finding the folder path to `struct.SomeStruct.html`. Check the `src/test/rustdoc/intra-paths.rs` test in this PR for a demo. The change was... a little invasive, but unlocks a really powerful mechanism for writing documentation that doesn't care about where an item was written to on the hard disk.
Items included:
 - [x] Make work with the hoedown renderer
 - [x] Handle relative paths
 - [x] Parse out the "path ambiguities" qualifiers (`[crate foo]`, `[struct Foo]`, `[foo()]`, `[static FOO]`, `[foo!]`, etc)
 - [x] Resolve foreign macros
 - [x] Resolve local macros
 - [x] Handle the use of inner/outer attributes giving different resolution scopes (handling for non-modules pushed to different PR)
Items not included:
 - [ ] Make sure cross-crate inlining works (blocked on refactor described in #47046 (comment))
 - [ ] Implied Shortcut Reference Links (where just doing `[::std::iter::Iterator][]` without a reference anchor will resolve using the reference name rather than the link target) (requires modifying the markdown parser - blocked on Hoedown/Pulldown switch and pulldown-cmark/pulldown-cmark#121)
 - [ ] Handle enum variants and UFCS methods (Enum variants link to the enum page, associated methods don't link at all)
 - [ ] Emit more warnings/errors when things fail to resolve (linking to a value-namespaced item without a qualifier will emit an error, otherwise the link is just treated as a url, not a rust path)
 - [ ] Give better spans for resolution errors (currently the span for the first doc comment is used)
 - [ ] Check for inner doc comments on things that aren't modules
I'm making the PR, but it should be noted that most of the work was done by Misdreavus 😄
(Editor's note: This has become a lie, check that commit log, Manish did a ton of work after this PR was opened `>_>`)

bors added a commit to rust-lang/rust that referenced this pull request

Jan 23, 2018
…Gomez,QuietMisdreavus,Manishearth
Implement RFC 1946 - intra-rustdoc links
rust-lang/rfcs#1946 #43466
Note for reviewers: The plain line counts are a little inflated because of how the markdown link parsing was done. [Read the file diff with "whitespace only" changes removed](https://github.com/rust-lang/rust/pull/47046/files?w=1) to get a better view of what actually changed there.
This pulls the name/path resolution mechanisms out of the compiler and runs it on the markdown in a crate's docs, so that links can be made to `SomeStruct` directly rather than finding the folder path to `struct.SomeStruct.html`. Check the `src/test/rustdoc/intra-paths.rs` test in this PR for a demo. The change was... a little invasive, but unlocks a really powerful mechanism for writing documentation that doesn't care about where an item was written to on the hard disk.
Items included:
 - [x] Make work with the hoedown renderer
 - [x] Handle relative paths
 - [x] Parse out the "path ambiguities" qualifiers (`[crate foo]`, `[struct Foo]`, `[foo()]`, `[static FOO]`, `[foo!]`, etc)
 - [x] Resolve foreign macros
 - [x] Resolve local macros
 - [x] Handle the use of inner/outer attributes giving different resolution scopes (handling for non-modules pushed to different PR)
Items not included:
 - [ ] Make sure cross-crate inlining works (blocked on refactor described in #47046 (comment))
 - [ ] Implied Shortcut Reference Links (where just doing `[::std::iter::Iterator][]` without a reference anchor will resolve using the reference name rather than the link target) (requires modifying the markdown parser - blocked on Hoedown/Pulldown switch and pulldown-cmark/pulldown-cmark#121)
 - [ ] Handle enum variants and UFCS methods (Enum variants link to the enum page, associated methods don't link at all)
 - [ ] Emit more warnings/errors when things fail to resolve (linking to a value-namespaced item without a qualifier will emit an error, otherwise the link is just treated as a url, not a rust path)
 - [ ] Give better spans for resolution errors (currently the span for the first doc comment is used)
 - [ ] Check for inner doc comments on things that aren't modules
I'm making the PR, but it should be noted that most of the work was done by Misdreavus 😄
(Editor's note: This has become a lie, check that commit log, Manish did a ton of work after this PR was opened `>_>`)

@petrochenkov petrochenkov added the T-dev-tools

Relevant to the development tools team, which will review and decide on the RFC.

label

Jan 30, 2018

Open

Closed

3 tasks

Closed

Closed

Closed

Open

Closed

Merged

bors Bot added a commit to crossbeam-rs/crossbeam that referenced this pull request

Sep 6, 2020
559: Use intra-doc links r=stjepang a=taiki-e
Switch to use [intra-doc links](rust-lang/rfcs#1946) in all crates. Previously there was a big bug on cross crate re-exports (rust-lang/rust#65983), but it has been fixed, so we can use this in crossbeam.
This also adds checks of the docs to CI.
560: Use collect::<Box<[_]>>() directly in ShardedLock::new() r=stjepang a=taiki-e
Co-authored-by: Taiki Endo <te316e89@gmail.com>

khvzak added a commit to mlua-rs/mlua that referenced this pull request

Oct 11, 2021

khvzak added a commit to mlua-rs/mlua that referenced this pull request

Oct 11, 2021

khvzak added a commit to mlua-rs/mlua that referenced this pull request

Oct 11, 2021

sdleffler pushed a commit to sdleffler/hv-lua that referenced this pull request

Nov 13, 2021

Read the original on github.com ↗