-
Notifications
You must be signed in to change notification settings - Fork 12.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update intra-doc link documentation to match the implementation #80874
Conversation
This comment has been minimized.
This comment has been minimized.
8458be1
to
0271791
Compare
Nice! Maybe it's good to also mention that both |
Good idea, done. |
That's weird, I've found that |
@@ -24,11 +24,29 @@ pub struct Foo4; | |||
pub struct Bar; | |||
``` | |||
|
|||
Unlike normal markdown, `[bar][Bar]` syntax is also supported without needing a | |||
`[Bar]: ...` reference link, and links are case-sensitive. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should probably note somewhere that non-intra-doc links are case-insensitive; see #80882.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ugh, #80882 is a mess. I think I'd prefer to see what the plan is there before updating the documentation.
namespace. In case of ambiguity, rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, `fn@`, `function@`, `mod@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`: | ||
## Namespaces and Disambiguators | ||
|
||
Paths in Rust have three namespaces: type, value, and macro. Item names must be unique within |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It may not be necessary, but do you want to note that the type namespace includes modules?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would prefer not to; if you get it wrong it will be clear from the error message. If we mention modules we should also say functions are in the value namespace, though.
characters will be ignored. You can see the full criteria for 'sufficiently like' in [the source | ||
code]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure if it's a good idea to link to the source code here. For one, it will very easily become out-of-date because it's tied to a particular commit. I think we should either skip this or include the list directly in the documentation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, I kind of prefer not to tie this down so we can update it in the future. Maybe I could change the commit hash to master
instead? That might have wrong line numbers though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe I could change the commit hash to
master
instead? That might have wrong line numbers though.
Yeah, I think that would be very confusing.
Hmm, I kind of prefer not to tie this down so we can update it in the future.
What do you mean? Documenting it isn't "tying it down".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So, this is a not a reference, this is a book, and I don't think it should go into that much detail. We do not need to document every last corner of the implementation here. Let's just drop this section.
- Improve wording - Use relative links - Use a proper list instead of a wall of text - Improve examples
It should, if not that's a bug. Feel free to open an issue if you run into it again. |
Links are resolved in the scope of the module where the item is defined, even | ||
when the item is re-exported. If a link from another crate fails to resolve, no | ||
warning is given. | ||
|
||
When re-exporting an item, rustdoc allows adding additional documentation to it. | ||
That additional documentation will be resolved in scope of the re-export, not | ||
the original, allowing you to link to items in the new crate. The new links | ||
will still give a warning if they fail to resolve. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These two paragraph seem contradictory. The first one says that links are resolved in the module where the item is defined, even when it's re-exported, while the second says that documentation you add on a re-export will be resolved in the re-export crate. Which one is it? :P
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The original links will be resolved in the original scope. The new links will be resolved in the new scope. The idea is for this to work:
// crate 1
/// Link to [f()]
pub struct S;
pub fn f() {}
// crate2
/// Link to [g()]
pub use crate1::S;
pub fn g() {}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you should say something like that in the docs, because I couldn't tell what you meant from the way it is right now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I couldn't think of a way to explain this better, but I did add an example of both scenarios.
This comment has been minimized.
This comment has been minimized.
Co-authored-by: Camelid <camelidcamel@gmail.com>
@@ -76,19 +96,66 @@ struct Foo {} | |||
fn Foo() {} | |||
``` | |||
|
|||
The following prefixes can be used: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd collapse this into a single sentence. Most people don't need to care about this, and rustdoc helps with diagnostics when they do.
trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which | ||
have no path and cannot be imported: | ||
|
||
- [`slice`](../std/primitive.slice.html) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd collapse this into a single sentence. Most people don't need to care about this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
overall this is written a little like a full reference; we don't need to cover everything, we should largely give space to things that are important to most users.
@Manishearth So....where does reference material for rustdoc go? |
I don't think there needs to be such in depth reference material for rustdoc. Like, so far in this pull request there's only one thing that I feel doesn't belong, and it's in the "rustdoc will ignore things that look like URLs" bit, which tbh i feel doesn't need to be documented at all, but either way, it's an extremely minor thing, and there aren't enough of these to warrant a separate book. The rest is just a matter of style: A reference book can get away with being as precise as it can, but this book should be concise when talking about things that don't matter as much, like the disambiguators -- nobody needs to learn about them, in fact I'd argue they don't really belong in this book either, but it's fine to just have a sentence. |
I feel like there should be a reference somewhere. It doesn't need to be the rustdoc book, but right now it's hard to find how things work and why. Really this is an ongoing problem I've seen with rustdoc where things are underspecified and changes happen without much discussion. Here are some concrete examples:
All of these individually are small, but they build up. I feel like "whatever the implementation does" is really not a good way to build software, especially when there's no much discussion about these changes and they just happen. |
I think for a first pass this stuff should be long comments in the source, or just extra documentation in a |
But I am strongly against putting something that basically only implementors need to care about in the book. My opposition to a separate in-depth reference is mostly that it's a lot of work for very little benefit, and we can get something much smaller done better, but I'm not strongly against that. Having a |
I agree it probably doesn't fit in the book, but I don't think this is something only implementors need to worry about. These are all user-facing things that affect behavior, even if they're edge cases. Anyway, I'll update this to not have quite so much detail and maybe open a tracking issue for the other things. |
I'll point out that subtle edge cases of a lot of the things in the compiler are not user-facing-documented either. Things like "we try to figure out if something is supposed to be an intra-doc link with magic" and "type inference does magic" should be documented, but the precise details of what the magic is doesn't really need to be user-facing. It's sufficient for people to know that magic is going on, and if there are problems they can root cause it to the magic, and do something to appease the magic. Understanding the magic can be useful here, but really what you just need to know is how to bypass it; and for intra-doc links that's basically using the discriminants, and for inference it's using specific types. |
This comment has been minimized.
This comment has been minimized.
3768362
to
86e2fcb
Compare
This comment has been minimized.
This comment has been minimized.
This is ready for review (I finally figured out the CI error). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bors r+ rollup
@bors r+ rollup |
📌 Commit c2694f1 has been approved by |
Rollup of 10 pull requests Successful merges: - rust-lang#80189 (Convert primitives in the standard library to intra-doc links) - rust-lang#80874 (Update intra-doc link documentation to match the implementation) - rust-lang#82376 (Add option to enable MIR inlining independently of mir-opt-level) - rust-lang#82516 (Add incomplete feature gate for inherent associate types.) - rust-lang#82579 (Fix turbofish recovery with multiple generic args) - rust-lang#82593 (Teach rustdoc how to display WASI.) - rust-lang#82597 (Get TyCtxt from self instead of passing as argument in AutoTraitFinder) - rust-lang#82627 (Erase late bound regions to avoid ICE) - rust-lang#82661 (:arrow_up: rust-analyzer) - rust-lang#82691 (Update books) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
r? @Manishearth
cc @camelid @m-ou-se
Relevant PRs:
Relevant issues:
.
or[]
#54191I haven't documented things that I consider 'just bugs', like #77732, but I have documented features that aren't implemented, like #78800.