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.
added
T-doc
labels
Mar 7, 2017bors 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
added
the
T-dev-tools
label
Jan 30, 2018Open
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, 2020559: 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>