Question:
RFC: RFC PR: Todo: [x] Land [x] Make it work with cross-crate imports (, ) [x] Make it work for proc macros [x] Make it warn more on resolution errors () [x] Make warnings/errors use better spans than the first line of docs [x] first step: attribute () [x] point to actual link in doc comment () [x] Add lint for link resolution failure () [x] Implied Shortcut Reference Links () [x] blocked on and [x] Enum variants and UFCS/associated methods () [x] Primitives () [x] Use the right resolution scopes for inner doc comments on things that aren't modules () [x] Handle fields and variants () [x] Handle fields inside struct variants () [x] Support () [x] Write documentation () [x] Stabilization ( - current impl is gated to only run on nightly, but does not require a feature gate) [x] Handle methods from traits implementations [x] Support anchors () [x] Support missing primitive types (such as slices) () [x] Allow referring to (for on ) [x] Fix current crate linking when no module is provided in the path (for example, won't link to the crate's type for some reason) [x] reexports can break intra-doc links () [x] Support associated items in contexts other than documenting a trait method () Other related issues: [x] Suppress privacy errors with document-private-types (, fix at ) [x] provide option to turn intra-link resolution errors into proper errors ()
Preliminary implementation notes: Getting just the links from the markdown is relatively straightforward. You'll need to do this twice, to capture the behavior in both the Hoedown and Pulldown markdown renderers. Thankfully, each has a way of capturing links as they are parsed from the document. (While capturing the link you can also look for the "struct/enum/mod/macro/static/etc" marker to aid in resolution down the line.) In Hoedown, the function in captures all the events as they are captured. Hoedown uses a system of registering callbacks on the renderer configuration to capture each event separately. The event and its related function pointer signature are already present in the file, so you would need to create and use that callback to capture and modify links as they appear. For Pulldown, the parser is surfaced as an of events. There are already a handful of iterator wrappers present in , so adding another one (and using it in the farther down) shouldn't be a big deal. I'm... honestly not that familiar with how Pulldown represents link definitions in its Event/Tag enums, so more research would be needed to effectively get link text for that. Now, with the links in hand, you need to do two things, neither of which i know offhand since they involve interfacing with the compiler: Attempt to parse the link as a path (if it's not a valid Rust path, just emit the URL as-is and skip the rest of this) Resolve the path in the "current" module (emit a warning if resolution fails) Presumably there's a way to make the resolution come up with a DefId? Even after cleaning the AST, rustdoc still deals in those, so if that's the case there are ways to map that to the proper relative link.
I've got a WIP going on in , which works off of Misdreavus' WIP (they did most of the work).
Note that that branch is now live as , which i'm polishing and finishing up.
Note for people watching this thread but not We're trying to wind that PR down to get a minimal version landed, so an initial implementation is fairly close.
One thing that appears to not work in (and I don't think is ever explicitly addressed in the RFC) is how to link to primitives like or .
Yeah I have to investigate that
should we turn the error into a warning ? I don't like the idea of crate docs breaking because someone introduced a name into a glob import
does rustdoc have some idea of "lint levels"? What are the current deprecation warnings? Just println!s?
We can just instead. rustc can emit warnings not tied to actual warning names. There are no lint levels.
Alright, let's do that for now. In the end I'd really like to have a way to check the docs for errors but that's a more involved/fragile process I imagine. Manish Goregaokar < am Mi. 24. Jan. 2018 um 09:17:
Shortcut links being implemented at
If will work as part of this RFC, will also work for linking to specific sections of that documentation?
Not currently. This can be implemented. ९ मार्च, २०१८ २:१४ म.उ. रोजी, "Sunjay Varma" <notifications लिहिले:
I can't seem to get links to struct fields to work (either or ). Am I missing something, or is it not implemented? If not, is it planned to be supported?
should work
Oh, wait, no, struct fields don't work yet. We can add those later.
Was their any discussion about linking to dev-dependencies? For example in a heavy crate like it may be that some sub-crates want to link back to the prelude at directly. One way this could be done is simply including dev-dependencies in the doc build and relying on the implicit use of crates in Edition 2018.
Edge-case error I found: apparently, if a crate is marked as , then this also applies to autolinks; I can't link in a crate even if the crate itself doesn't need it. This seems like a relatively easy bug to fix imho.
Based on a conversation just now: It would be cool if we could add in a section to pages to collect "back-links", or a listing of pages that contain doc-links to a given page.
One thing I would really love was if in the documentation for some type linked to automatically. It makes it a little easier to write documentation text that flows nicely and doesn't seem awkward (I know you're talking about a method on , that's the text I'm reading!)
That would be ambiguous though, if a top level item existed with the same name. I would personally be happy if [Self::method] worked.
Maybe works today? (As in, .) We could establish a priority to resolve ambiguities.
is nice, though I would want it to be rendered as just . This shows up a lot in documentation of the form: If these cases, and would seem a bit redundant, and make the sentence harder to follow.
I think it should be fine if it was written as , as it is unambiguous, but rustdoc would recognize that it's a method, and rendered it as just . If the user really wanted to keep the part in the rendered version for some reason, they could just write . EDIT: Jeezus, I was on phone, and couldn't find the backtick on the virtual keyboard.
In the futures crate we get a lot of intra doc resolution warnings. The curious thing is that these warnings are always for another crate than the crate for which the docs are currently being built. E.g. on its own builds with no warnings. However, , which depends on , builds with warnings from . https://travis-
Should "point to actual link in doc comment" be checked off since is merged?
Also "Add lint for link resolution failure" ()
And looks like "Support Self" was in .
Checked the 3 of them.
I'm finding a resolution failure that is puzzling me: Neither nor resolve.
It makes sense to me that bazFoo::bazusestatement) so that seems fine to me. That doesn't resolve either seems odd. Does resolution work when written on associated methods?
doesn't resolve the same way IIRC, so we'd have to explicitly support it
As said.
This is only tangentially related, but is there any way at all we could help improve the situation for 's that are generated from rustdoc with this change? I'm thinking specifically of , though I'm sure there are other cases where the relative links won't resolve. Could we generate absolute links instead based on the key in (if present)?
Here's another interesting issue: If you take the module docs in and remove the Rcstd is organized. Does this have to do with the cross-crate imports bullet point above?
When building docs with deny warnings on nightly, currently you get a bunch of errors related to intra rustdoc links not being resolvable. It looks like the errors are coming from building docs for the standard library itself. Can we add something to the Rust CI to check for these warnings, or otherwise disable issuing these warnings when building downstream crates? Example: <details<p</p</details
I was actually putting together a PR to deny the warnings, but it appears that some of the existing failures are caused by issues in the implementation rather than errors in the documentation. So, like you said, it might be best to silence them when documenting downstream crates for now.
I assume that "Make it work with cross-crate imports" in the OP is referring to things like docs on externally-defined trait implementations failing to resolve and causing warnings to appear, even though the docs are valid in the crate that defined the trait? Is this still blocked on something else (and if so, is there somewhere with more details for tracking it than a comment on the old PR)?
The issue is hitting in is still happening and is a serious blocker for me-- even when building with --no-deps, I'm getting warnings and errors from upstream documentation resolution failures.
(am unblocked through the magic of RUSTDOC env var, shell scripts, and the --cap-lints setting, but still this should get fixed XD)
This is enough to trigger a failure right now. (I'll need to narrow it down, but using a crate with some specific use of intra-links will work.) I thought i'd fixed this kind of erroneous error with but it turns out it wasn't good enough. I'm building/testing a fix right now that refuses to run link collection on non-local items. It may be a bit drastic (and breaks docs which actually work in this situation) but it finally silence this kind of issue until we can actually support them.
Narrowed it down: I bet the PR i linked doesn't touch this impl because it's generic, so it could apply to any number of local items.
In Rocket, we have two libraries in a workspace: a core library, , and a contrib library . is not a dependency of , but refers to in its documentation often. Because is not a dependency of , cross-crate links are not resolving: Is there any workaround to this? I've tried adding manually via , as well as using , but neither work. Even if the latter worked, it isn't a great solution as it'll produce absolute links, partially defeating the purpose. In general, I think and/or should automatically add all crates in the same workspace to the resolution domain for inter-crate links, making something like work out of the box.
have you tried adding a feature to the lib that you set when building docs and that enables an optional dependency on ? (Sorry to respond here without having followed this issue or impl much!)
This will cause issues with the docs when built outside the workspace, e.g. when someone runs to get locally built docs in their project. Changing or having an optional feature has similar problems. I suggested including during doc builds to solve the same issue, or maybe there could be an additional section?
I considered that, but unfortunately that would introduce a cyclic dependency. I instinctively tried that - placing the dependency in - actually. Although I secretly hoped it didn't work as I really don't want to build/check when working on . A special section would resolve this particular issue if it allowed cyclic dependencies.
Currently it's possible to link to fields of structs via a form of psuedo-path: Similarly it would be useful if it were possible to link to fields of a variant of an enum, probably via the same sort of psuedo-path:
I'm trying to ascertain the readiness of this feature for release use, and was hoping the tracking issue might help. While it is working great for me on recent nightly builds, on the just released stable rust 1.30.0 ( 2018-10-24), I'm surprised to find that the feature still isn't complete: some links using rust paths aren't resolved to html links. Is this feature intended to be nightly only? Or is there flags or feature's to be set in order to use it with the rust stable channel? Should I file a new issue for the missed links on 1.30?
There's a big hole in the current implementation, documentation for re-exported items doesn't work. Re-exports are used a lot in the ecosystem so this is a stabilization blocker. It's nontrivial to implement since it requires some architectural changes. Also, yeah, file issues for missing links, cc me. On Thu, Oct 25, 2018, 6:12 PM David Kellum <:
I'm not privy to how Rust tends to handle these sorts of things, so I realize this might go against established practice, but it seems to me like it would be useful to have what currently exists in stable, but just not promoted as something that actually works. It's not dangerous and is useful in its current state. I guess the risk is that nobody ever finishes the support for re-exports and we're stuck with a half working feature?
The problem is more that the brokenness of re-exports is subtle. If folks start using this in documentation, they may not notice that it's broken in re-exports, which will end up showing ugly documentation. I'm not going to push back strongly though, if the docs team feels that early stabilization is okay that sounds good to me. On Thu, Oct 25, 2018, 6:37 PM Peter Wagenet <:
I've found it super useful in its current form, but I can see the worry around things being subtly broken.
I misinterpreted what I was initially seeing on 1.30: all, not just some, rust path style links (this feature) are not resolved on this latest (and prior) stable releases. Besides that not being explained anywhere I can find, the output is slightly confusing because the implicit type links are shown as obviously broken, e.g. "[]" where as links explicitly using a rust path are included verbatim, e.g. , as would be expected without this feature being present. As it seems now the intent for this was to be nightly-only until further along, shouldn't this tracking issue be edited to include the following, as it might save the next prospective user some confusion ( [ ] Stabilization PR (current implementation is nightly only, but not feature gated) I agree that this is value add as found on current nightly. Authors can just avoid using the new link style for re-exports, as well as links to other crates which are not dependencies, until these are resolved. But as it stands, its a bit difficult to justify using the feature when it will not generate correct links for a user-local even on the latest stable, not to mention the minimum stable rust version. Please consider if keeping this off for stable, with no option or flag, is now more likely to cause trouble with broken links (as this starts getting used with nightly) vs any regressions stabilizing might otherwise cause, given that the new style link targets would never have worked without the feature?
Random idea: If it is planned to keep this semi-usable for a few more months, it might interesting to see if we can make nightly rustdoc optionally print out the generated relative links (with obvious issues when docs are rendered in more than one place). I don't think we have precendence for this, but if you someone wants to have a fun project, they might even try to integrate this with rustfix (i.e., yield 'suggestion-like' output where you appen for each link).  You can use it right now, with the obvious missing features mentioned above. Since uses a nightly compiler version where the intra doc links work, a lot of people reading the docs for your crate will see the correct links. People trying to build the docs will be disappointed, though.
You are correct in your observations: The feature is currently written so that links will only ever resolve when running on a nightly (or locally-compiled) rustdoc. In any other situation, they will be passed through in the way you observed. The current implementation of intra-doc links is not only incomplete, as mentioned, but is also bug-ridden: There have long been issues of spurious "dead links" being found in crates which aren't using intra-doc links at all. This, combined with the fact that we emit a proper warning lint for these resolution errors, led to situations where innocent crates suddenly broke because they had set. To be honest, running this without a proper feature gate is shaky, in terms of how unstable features work in the rest of the compiler and rustdoc, but until recently i was uncertain if we could properly introduce a gate to the compiler without a matching use in rustc itself. (All the attributes that rustdoc currently uses are tied to attributes, so their check code is also in the compiler.) I would be willing to introduce a feature gate for this, since it would also stamp down on the false positive rate across the ecosystem. However, it leads to similar broken-link situations. Imagine crate A which uses intra-doc links, complete with having the feature set. Now imagine crate B, which re-exports items from crate A to inline them into its own documentation, but doesn't use intra-doc links itself. Because crate B doesn't have the feature set, now those links from the crate A items won't resolve, even if they were accidentally correct because those items were re-exported into the right positions! (This situation exists today; these crates are and , though the items from that re-exports don't have any links on them.) I'm very hesitant to "partially stabilize" these links, because of the subtleties with re-exports that mentioned. It's too easy to use any part of this feature and get it to a position where it doesn't work. And the major hurdle for making that work requires a deep compiler refactor that is hard to find a champion for. If it comes down to it, if there is another Rust All-Hands early next year like the one in Berlin earlier this year, i may try getting the right people in a room together to design this problem out. However, that won't be able to happen for another few months.
I wonder if the standard library crates will need special treatment by this feature? For example, the link to the constant in docs needs to resolve to or depending if the docs are being rendered as part of the libstd or liballoc docs.
Small bug report (let me know if this isn't the correct place to report this): Currently, intra-doc links respect in a way that I'm not sure that they should. It means that simple links like fail to link to the correct place in the standard library documentation.
Well, it's part of the issue indeed. I'll add a bullet point for it.
The problem is that we use the same resolver that the compiler has made - which means that it's affected by . To universally load in libstd for intra-doc links, we either need to totally ignore when building docs (which may cause erroneous compilation errors) or have some way to find and load libstd's information (and prelude, since you mentioned specifically) after rustdoc takes over from the compiler. I'm sure it's possible, but it's more cumbersome than it seems.
It definitely seems like one of those cases where what is technically correct and what is expected are different, and we should design in favor of the latter. The easiest stopgap solution I can see would be to add a new compiler attribute, , so that users can write:
Do I get it right that , , are not supported for path resolution? does not seem to throw a warning of failed resolution where the other two do. However it creates a link as: which obviously doesn't work.
Hmm, they should work, but I think the implementation is buggy around them right now. On Tue, Apr 30, 2019, 7:18 AM Naja Melan <:
Ok, we do seem to have success with actually, but is definitely broken.
I didn't see it mention in the RFC or this issue, but is there a way to link to a documentation header in another crate? For example, I'd like to link to the syntax header of the regex crate. I can do something like this: But not something like this (which would be preferred, as that would link to the correct version of the syntax documentation):
No, intra doc links doesn't currently support linking to sections. It could. It doesn't support linking to other either, but that's trickier to get right.
What do you mean by this? Quick testing shows that intra-rustdoc links works fine with locally available docs, or specified in a dependency, or overrides on the command line. If you're referring to the fact there's no default external doc location when isn't set, that is independent of the intra-rustdoc feature, it will presumably just work if is updated to be able to default that.
I mean the general case of linking to an external crate on if it's not a dependency of yours or you are not on
Ok, so just , which applies to all links to external documentation including intra-rustdoc links.
I filed , in which the "module disambiguator does not seem to be respected.
I filed to propose support for linking to sections, [link text][MyStruct#my-section].
I filed about recognizing as an intra doc link.
I'm not fan of such things... For instance, what should we do with Vec<StringVecStringSomeType<T, U, V`".
I would be on board with linking if and only if the type parameters in the link match the names of the type's generic parameters, for example would get linked but would not.
That'd force to check all the generic parameters, not very ideal...
Would you be able to clarify what is not ideal about checking generic parameters? Is it difficult to implement? If that's the only thing, would you consider accepting a PR that takes care of the implementation?
No it's not difficult. It's just not ideal because it creates additional rules that I find useless. The goal of a feature is to be simple enough to let users use it without having to wonder: it something I can do? will be the outcome? In this case, we can consider that the first point wouldn't be an issue but the second definitely would.
It would be great if there were better support for rendering this style of linking then, currently they have weird spacing, opened about it.
While this is unstable it should at least produce warnings with non-nightly compilers to avoid catching users off-guard: Opened as
I see that has been merged to add support for primitive types, however I'm trying to link to as well, to test if it's just polymorphic primitives, and it seems that might be the issue, since it also doesn't work as a intra-link. Am I missing something?
It's still very unstable and experimental. A lot remains to be done. Can you open an issue about it and cc me on it please?
Would it be possible to have this resolve links to trait implementation? For example:
Normally it should work as is. But like said above, it's still very experimental.
It doesn't seem to work for me... on
This comment isn't very helpful... Can you provide us details like the markdown, the context, etc... ?
Fully reproducible example:
So, trait methods aren't working. Thanks for the feedback. Adding it to the points.
I filed to have the disambiguator stripped from the link text in something like .
Is there any centralised documentation for how exactly this feature works, considering how it's changed so much from the initial RFC? Like, specifically document what kinds of links should work and which shouldn't, and if parts of the text are removed from the final result? Like, I get that it's not going to be stabilised any time soon, but many folks use this feature and it's hard to reason which things work and which don't at the moment.
The only thing blocking stabilization now is
Isn't documentation also a blocker?
That's usually a part of stabilization.
Is there any way to hide any prefix when linking to types not within the current module and not in scope when using shorthand links? I notice in some of my documentation, I have some types imported, and can link to them using MyStructcrate::OtherStruct`, which looks a bit off in the documentation. I realise I can name the link whatever I want and then turn it into an actual link later by adding a reference, but that increases the bloat of the comment in the code itself. I guess it's a minor thing, and there's no clean way to solve this that isn't probably at least somewhat surprising to some, but I wanted to mention it nonetheless.
Have you tried something like:
One way that I tend to do this is using the (currently unstable, but pending stabilisation in ) . i.e., at the top of the file, I put: and then you can reference the type without the prefix. You can do this without the by simply adding , although I prefer the former as it will still lint if you don't actually use the import.
Could someone in the know please file an issue around "Handle fields inside struct variants" so that I know what might be needed in order to close off that blocker?
It's not a blocker. It's about giving the ability to link directly to a struct field by naming it in the link.
Isn't that ambiguous when there is also an inherent method with the same name? It's also "syntactically unnatural" to refer to struct fields in this way, though I can't think of a better way right now.
Yeah, that's why there's no issue for it, it's something we may want to add and if we do we'd have to figure out how. It's not a blocker. Thanks, -Manish Goregaokar Mikhail Zabaluev <:
Aha, thanks. I misunderstood the presence of something in the top comment with a tickybox as being something which had to be done. Is there an issue capturing the desire to link to a struct's field so that it doesn't get lost if this issue is closed? Or is there a process for splitting out remaining issues when we close a tracking issue?
We can file an issue now if you want, but basically any leftover non blockers will be filed as issues once this is closed. On Sat, Nov 9, 2019, 11:23 PM Daniel Silverstone <:
Okay, if raising issues when this closes is the process then that's perfect. I'm not in a rush to have that issue, I was just trying to properly understand (a) what was actually considered blocking for stabilisation, and (b) what the process was to deal with remaining things if it wasn't all blocking. Thank you for clarifying things
Cross crate imports and documentation are the only stabilization blockers AIUI. Documentation can be done during the stabilization process.
If someone wants to add docs earlier they can be to the unstable book, and then moved over to the reference.
seems like has a similar thing in progress at for
See also:
Oooh interesting, thank you. I shall have to have a look when gets closer to completion. I have plenty to be doing before I try for the better resolution, so if their work makes life easier for us, then that's excellent.
You should coordinate with them and see if there's a way y'all can work together! It's possible their work is already sufficient for your purposes here. On Sun, Nov 10, 2019, 11:52 PM Daniel Silverstone <:
When I tried using intra-doc links in libstd docs a few months ago, I was told they are still experimental and should not be used yet. What is the current status? When writing new docs / adding new links to existing docs, should I use intra-doc links?
Would it be possible to land the current intra-doc feature without cross crate imports? That would hit most of my needs for intra-doc resolution and still leaves open the option to land cross-crate imports later.
The problem is that anyone might re-export a type from your crate and then the documentation will be broken.
So the user of the feature can't know in advance when it will break. I guess we could still stabilize it with this caveat and request people to work with upstream authors to remove these links when reexporting.
If you're targetting docs built by it should be "fine". But as long as we don't have everything fixed, I don't think this is a good idea to stabilize it yet.
I don't if this is already on someone's radar but, linking to re-exported macros doesn't work at the moment. Simple test case: In : It fails with the following: Versions: rustc 1.43.0-nightly ( 2020-03-08) cargo 1.43.0-nightly ( 2020-03-02)
this is
This should be fixed now. See issue, MR,
Perhaps this is fixed now, see issue: MR: If not please. please provide a minimal example for it to clarify it.
I don't understand how to link to a re-exported procedural macro. The RFC indicates that linking to a macro is possible, but none of my attempts appear to successfully link. the- the-
the re-export is the problem, see As a workaround, you might be able to use the absolute path (), but I haven't tested that.
Yeah, that was one I tried in my project but didn't reflect in the reproduction. It didn't seem to work either. <details<summaryAttempts</summary</details
I'm not sure, right now cross-doc links are pretty broken. Hopefully will land in the next few weeks, you could try again afterwards.
the cross crate bug is unrelated to the one being described by You should totally be able to link to a in the current implementation, so what describes is an independent bug
Can confirm that linking to works, but not if it's a proc macro being used. Macro scoping is weird so that's probably it.
Oh, this has nothing to do with pub use, we're just completely incapable of linking to derive macros
Filed , thanks
Note: once lands all of the blocker issues for this will have resolved and we should be a go for stabilizing the feature with docs. Note that it has baked as nightly-only for ages now.
I'll write documentation once it's merged then. We still have a few other points which need to be solved before stabilization though, but we're getting close! :)
I haven't had time to make a minimal repro, but there still appears to be an issue with linking to free-functions on cross-crate inlined docs like even using the from .
I've already got some of the docs written. It's not clear to me if the remaining issues should block stabilization, I think they can be treated as just another bug. We don't typically block stabilization on minor bugs whose fix will not impact the feature.
Do we have a general consensus on what kinds of changes are considered major or minor when it comes to doc syntax?
I don't think there are or needs to be rigid rules around that. When a feature is considered for stabilization, the relevant team looks at the status of the feature, and decides if it's ready. Like I said, typically bugs where the fix is not likely to severely change the feature are okay to have. In this case the major blocker, the cross-crate issue, was one where we weren't even sure if it was possible to implement, and it might have changed how the feature worked. It was also just a major piece of functionality. The current remaining issues are linking to std: this is a quality of life improvement where you can still link to items from a crate. The other one is about linking to the docs of the slice primitive, which is also a quality of life improvement, since people do that rarely.
I don't think there need to be strict rules, but I was mostly asking because I figure that this might come up more as rustdoc becomes more robust and changes to its syntax can throw deny-by-default warnings. My general assumption is that regardless of whether something might "break" that docs are considered separate enough to ignore these issues in favour of pushing out changes sooner, but I figure that a potential clarification on that might be helpful to avoid this confusion in the future.
oh that's fair. When it comes to lints the general Rust stabilty model is that new warn-by-default lints are always okay, deny-by-default lints should usually go through some cycles of warn-by-default unless there are special circumstances.
Okay, so I've narrowed bug down to the check in failing. Removing that line lets the link work just fine.
Annoyingly, any attempt to narrow down the testcase is failing for me. What's happening though is that the defid is absent from the accesslevels map. I'm not sure why.
Aha, it's the . Moving that to the end of the file fixes the issue . I'll try to file a bug about this.
FWIW the following part doesn't seem to occur anymore. This might have been an issue during the edition changes to resolution
Removing the no_std issue in the list because is actually a broader rustdoc bug
FWIW, I support stabilizing even with the remaining bugs. This flag is already used pervasively, for example, I believe all of uses this.
There's a WIP PR implementing resolving intra-rustdoc links, and traditional path-based links, in rust-analyzer .
That's really great, thanks!
Should we add suggestions to part of the tracking issue? For example, Could be Or we could guide them to do (I personally am not sure how to do this, I wish I could help out with diagnostics )
I think this should be a separate issue, it shouldn't block stabilizing the feature.
File a separate issue. Also the diagnostics here should be to suggest IMO.
I think it's a fair bit more involved to introduce this diagnostic fwiw
Status update: All the code for this has been written (that I know of), it's just waiting on a very long PR trail: -Once that is done, we can make a stabilization PR . The beta release is on Tuesday, which this will most likely miss; if it miraculously makes Tuesday we'll delay stabilization until afterwards because makes a lot of internal changes and should see a full 6 weeks on nightly before making it to beta. Additionally I'd love to see merged before since I expect it to improve rustdoc's performance quite a lot. That shouldn't block intra-doc links, though. EDIT: this landed
feel free to include in btw, we can land both at once
I'd rather not, is a good change even if we have to revert . Also it can be rolled-up and shouldn't be.
Once that is done we'll have an initial functional implementation. The next step is testing it. A big part of that will be to start using it in the docs and seeing if it can fix the issues it was designed for (, ).
We have had a functional implementation for three years now. It has been used in the stdlib docs for ages, and is used across the ecosystem. The ability for reexports to work correctly was a blocker to stabilization, but it is not a huge feature that will be used a lot. The reason stabilization was blocked on reexports was that we determined that the bug fix could be complicated and might require rearchitecting the feature, which made us reluctant to stabilize earlier.
I hadn't seen these issues earlier, and we should absolutely fix them using intra doc links, but I don't want to block stabilization on that. We've had this feature mostly working for ages.
Alright, so the current status of this is that we have a stack of PRs blocking all remaining major issues (, ): - - - Between and myself, we hope to stabilize this shortly thereafter. will be filing an FCP but as we're currently mostly waiting for the final chips to fall in place, I wanted to front-load some of the discussions that may happen during that FCP. Hopefully when we make that FCP it is simply some rubber-stamping if we have these discussions earlier. What are your thoughts on stabilizing this shortly after the last few patches land? I recall having some concerns. I don't recall if has said anything on this point. My position on this (I think this is shared by Guillaume and Joshua) is that this feature has been cooking on nightly for three years now. The cross-crate import issue was a blocker not because it was a major piece of functionality, but rather because there was a chance we wouldn't be able to implement it in a neat manner and would paint ourselves into a corner by committing to it. It's clear that that's not the case. If we're worried about the code for cross-crate imports itself being broken, that's what the release train schedule is for -- we can undo these patches and stabilization for twelve weeks if this happens.
I think that once the remaining stack lands, we're in good shape to stabilise. There're bound to be corner cases we've not found etc. and documentation which could be improved, but getting this out and usable by the general developer community will be immensely useful.
has landed, so now we're ready for stabilization. should land soon
Stabilization PR is ready
After this is no longer the case. Should the RFC be updated?
go for it
Triage: has been merged, so its mark can be checked, I believe?
Hi, does someone knows how to write intra-rustdoc links to ? I'm not sure if this is not implemented or if I'm writing incorrectly. Have tried those, but they are not working:

use rustc_data_structures::stable_set::FxHashSet; use rustc_errors::{Applicability, DiagnosticBuilder}; use rustc_expand::base::SyntaxExtensionKind; <del> use rustc_feature::UnstableFeatures; </del> use rustc_hir as hir; use rustc_hir::def::{ DefKind,


Question:
RFC: RFC PR: Todo: [x] Land [x] Make it work with cross-crate imports (, ) [x] Make it work for proc macros [x] Make it warn more on resolution errors () [x] Make warnings/errors use better spans than the first line of docs [x] first step: attribute () [x] point to actual link in doc comment () [x] Add lint for link resolution failure () [x] Implied Shortcut Reference Links () [x] blocked on and [x] Enum variants and UFCS/associated methods () [x] Primitives () [x] Use the right resolution scopes for inner doc comments on things that aren't modules () [x] Handle fields and variants () [x] Handle fields inside struct variants () [x] Support () [x] Write documentation () [x] Stabilization ( - current impl is gated to only run on nightly, but does not require a feature gate) [x] Handle methods from traits implementations [x] Support anchors () [x] Support missing primitive types (such as slices) () [x] Allow referring to (for on ) [x] Fix current crate linking when no module is provided in the path (for example, won't link to the crate's type for some reason) [x] reexports can break intra-doc links () [x] Support associated items in contexts other than documenting a trait method () Other related issues: [x] Suppress privacy errors with document-private-types (, fix at ) [x] provide option to turn intra-link resolution errors into proper errors ()
Preliminary implementation notes: Getting just the links from the markdown is relatively straightforward. You'll need to do this twice, to capture the behavior in both the Hoedown and Pulldown markdown renderers. Thankfully, each has a way of capturing links as they are parsed from the document. (While capturing the link you can also look for the "struct/enum/mod/macro/static/etc" marker to aid in resolution down the line.) In Hoedown, the function in captures all the events as they are captured. Hoedown uses a system of registering callbacks on the renderer configuration to capture each event separately. The event and its related function pointer signature are already present in the file, so you would need to create and use that callback to capture and modify links as they appear. For Pulldown, the parser is surfaced as an of events. There are already a handful of iterator wrappers present in , so adding another one (and using it in the farther down) shouldn't be a big deal. I'm... honestly not that familiar with how Pulldown represents link definitions in its Event/Tag enums, so more research would be needed to effectively get link text for that. Now, with the links in hand, you need to do two things, neither of which i know offhand since they involve interfacing with the compiler: Attempt to parse the link as a path (if it's not a valid Rust path, just emit the URL as-is and skip the rest of this) Resolve the path in the "current" module (emit a warning if resolution fails) Presumably there's a way to make the resolution come up with a DefId? Even after cleaning the AST, rustdoc still deals in those, so if that's the case there are ways to map that to the proper relative link.
I've got a WIP going on in , which works off of Misdreavus' WIP (they did most of the work).
Note that that branch is now live as , which i'm polishing and finishing up.
Note for people watching this thread but not We're trying to wind that PR down to get a minimal version landed, so an initial implementation is fairly close.
One thing that appears to not work in (and I don't think is ever explicitly addressed in the RFC) is how to link to primitives like or .
Yeah I have to investigate that
should we turn the error into a warning ? I don't like the idea of crate docs breaking because someone introduced a name into a glob import
does rustdoc have some idea of "lint levels"? What are the current deprecation warnings? Just println!s?
We can just instead. rustc can emit warnings not tied to actual warning names. There are no lint levels.
Alright, let's do that for now. In the end I'd really like to have a way to check the docs for errors but that's a more involved/fragile process I imagine. Manish Goregaokar < am Mi. 24. Jan. 2018 um 09:17:
Shortcut links being implemented at
If will work as part of this RFC, will also work for linking to specific sections of that documentation?
Not currently. This can be implemented. ९ मार्च, २०१८ २:१४ म.उ. रोजी, "Sunjay Varma" <notifications लिहिले:
I can't seem to get links to struct fields to work (either or ). Am I missing something, or is it not implemented? If not, is it planned to be supported?
should work
Oh, wait, no, struct fields don't work yet. We can add those later.
Was their any discussion about linking to dev-dependencies? For example in a heavy crate like it may be that some sub-crates want to link back to the prelude at directly. One way this could be done is simply including dev-dependencies in the doc build and relying on the implicit use of crates in Edition 2018.
Edge-case error I found: apparently, if a crate is marked as , then this also applies to autolinks; I can't link in a crate even if the crate itself doesn't need it. This seems like a relatively easy bug to fix imho.
Based on a conversation just now: It would be cool if we could add in a section to pages to collect "back-links", or a listing of pages that contain doc-links to a given page.
One thing I would really love was if in the documentation for some type linked to automatically. It makes it a little easier to write documentation text that flows nicely and doesn't seem awkward (I know you're talking about a method on , that's the text I'm reading!)
That would be ambiguous though, if a top level item existed with the same name. I would personally be happy if [Self::method] worked.
Maybe works today? (As in, .) We could establish a priority to resolve ambiguities.
is nice, though I would want it to be rendered as just . This shows up a lot in documentation of the form: If these cases, and would seem a bit redundant, and make the sentence harder to follow.
I think it should be fine if it was written as , as it is unambiguous, but rustdoc would recognize that it's a method, and rendered it as just . If the user really wanted to keep the part in the rendered version for some reason, they could just write . EDIT: Jeezus, I was on phone, and couldn't find the backtick on the virtual keyboard.
In the futures crate we get a lot of intra doc resolution warnings. The curious thing is that these warnings are always for another crate than the crate for which the docs are currently being built. E.g. on its own builds with no warnings. However, , which depends on , builds with warnings from . https://travis-
Should "point to actual link in doc comment" be checked off since is merged?
Also "Add lint for link resolution failure" ()
And looks like "Support Self" was in .
Checked the 3 of them.
I'm finding a resolution failure that is puzzling me: Neither nor resolve.
It makes sense to me that bazFoo::bazusestatement) so that seems fine to me. That doesn't resolve either seems odd. Does resolution work when written on associated methods?
doesn't resolve the same way IIRC, so we'd have to explicitly support it
As said.
This is only tangentially related, but is there any way at all we could help improve the situation for 's that are generated from rustdoc with this change? I'm thinking specifically of , though I'm sure there are other cases where the relative links won't resolve. Could we generate absolute links instead based on the key in (if present)?
Here's another interesting issue: If you take the module docs in and remove the Rcstd is organized. Does this have to do with the cross-crate imports bullet point above?
When building docs with deny warnings on nightly, currently you get a bunch of errors related to intra rustdoc links not being resolvable. It looks like the errors are coming from building docs for the standard library itself. Can we add something to the Rust CI to check for these warnings, or otherwise disable issuing these warnings when building downstream crates? Example: <details<p</p</details
I was actually putting together a PR to deny the warnings, but it appears that some of the existing failures are caused by issues in the implementation rather than errors in the documentation. So, like you said, it might be best to silence them when documenting downstream crates for now.
I assume that "Make it work with cross-crate imports" in the OP is referring to things like docs on externally-defined trait implementations failing to resolve and causing warnings to appear, even though the docs are valid in the crate that defined the trait? Is this still blocked on something else (and if so, is there somewhere with more details for tracking it than a comment on the old PR)?
The issue is hitting in is still happening and is a serious blocker for me-- even when building with --no-deps, I'm getting warnings and errors from upstream documentation resolution failures.
(am unblocked through the magic of RUSTDOC env var, shell scripts, and the --cap-lints setting, but still this should get fixed XD)
This is enough to trigger a failure right now. (I'll need to narrow it down, but using a crate with some specific use of intra-links will work.) I thought i'd fixed this kind of erroneous error with but it turns out it wasn't good enough. I'm building/testing a fix right now that refuses to run link collection on non-local items. It may be a bit drastic (and breaks docs which actually work in this situation) but it finally silence this kind of issue until we can actually support them.
Narrowed it down: I bet the PR i linked doesn't touch this impl because it's generic, so it could apply to any number of local items.
In Rocket, we have two libraries in a workspace: a core library, , and a contrib library . is not a dependency of , but refers to in its documentation often. Because is not a dependency of , cross-crate links are not resolving: Is there any workaround to this? I've tried adding manually via , as well as using , but neither work. Even if the latter worked, it isn't a great solution as it'll produce absolute links, partially defeating the purpose. In general, I think and/or should automatically add all crates in the same workspace to the resolution domain for inter-crate links, making something like work out of the box.
have you tried adding a feature to the lib that you set when building docs and that enables an optional dependency on ? (Sorry to respond here without having followed this issue or impl much!)
This will cause issues with the docs when built outside the workspace, e.g. when someone runs to get locally built docs in their project. Changing or having an optional feature has similar problems. I suggested including during doc builds to solve the same issue, or maybe there could be an additional section?
I considered that, but unfortunately that would introduce a cyclic dependency. I instinctively tried that - placing the dependency in - actually. Although I secretly hoped it didn't work as I really don't want to build/check when working on . A special section would resolve this particular issue if it allowed cyclic dependencies.
Currently it's possible to link to fields of structs via a form of psuedo-path: Similarly it would be useful if it were possible to link to fields of a variant of an enum, probably via the same sort of psuedo-path:
I'm trying to ascertain the readiness of this feature for release use, and was hoping the tracking issue might help. While it is working great for me on recent nightly builds, on the just released stable rust 1.30.0 ( 2018-10-24), I'm surprised to find that the feature still isn't complete: some links using rust paths aren't resolved to html links. Is this feature intended to be nightly only? Or is there flags or feature's to be set in order to use it with the rust stable channel? Should I file a new issue for the missed links on 1.30?
There's a big hole in the current implementation, documentation for re-exported items doesn't work. Re-exports are used a lot in the ecosystem so this is a stabilization blocker. It's nontrivial to implement since it requires some architectural changes. Also, yeah, file issues for missing links, cc me. On Thu, Oct 25, 2018, 6:12 PM David Kellum <:
I'm not privy to how Rust tends to handle these sorts of things, so I realize this might go against established practice, but it seems to me like it would be useful to have what currently exists in stable, but just not promoted as something that actually works. It's not dangerous and is useful in its current state. I guess the risk is that nobody ever finishes the support for re-exports and we're stuck with a half working feature?
The problem is more that the brokenness of re-exports is subtle. If folks start using this in documentation, they may not notice that it's broken in re-exports, which will end up showing ugly documentation. I'm not going to push back strongly though, if the docs team feels that early stabilization is okay that sounds good to me. On Thu, Oct 25, 2018, 6:37 PM Peter Wagenet <:
I've found it super useful in its current form, but I can see the worry around things being subtly broken.
I misinterpreted what I was initially seeing on 1.30: all, not just some, rust path style links (this feature) are not resolved on this latest (and prior) stable releases. Besides that not being explained anywhere I can find, the output is slightly confusing because the implicit type links are shown as obviously broken, e.g. "[]" where as links explicitly using a rust path are included verbatim, e.g. , as would be expected without this feature being present. As it seems now the intent for this was to be nightly-only until further along, shouldn't this tracking issue be edited to include the following, as it might save the next prospective user some confusion ( [ ] Stabilization PR (current implementation is nightly only, but not feature gated) I agree that this is value add as found on current nightly. Authors can just avoid using the new link style for re-exports, as well as links to other crates which are not dependencies, until these are resolved. But as it stands, its a bit difficult to justify using the feature when it will not generate correct links for a user-local even on the latest stable, not to mention the minimum stable rust version. Please consider if keeping this off for stable, with no option or flag, is now more likely to cause trouble with broken links (as this starts getting used with nightly) vs any regressions stabilizing might otherwise cause, given that the new style link targets would never have worked without the feature?
Random idea: If it is planned to keep this semi-usable for a few more months, it might interesting to see if we can make nightly rustdoc optionally print out the generated relative links (with obvious issues when docs are rendered in more than one place). I don't think we have precendence for this, but if you someone wants to have a fun project, they might even try to integrate this with rustfix (i.e., yield 'suggestion-like' output where you appen for each link).  You can use it right now, with the obvious missing features mentioned above. Since uses a nightly compiler version where the intra doc links work, a lot of people reading the docs for your crate will see the correct links. People trying to build the docs will be disappointed, though.
You are correct in your observations: The feature is currently written so that links will only ever resolve when running on a nightly (or locally-compiled) rustdoc. In any other situation, they will be passed through in the way you observed. The current implementation of intra-doc links is not only incomplete, as mentioned, but is also bug-ridden: There have long been issues of spurious "dead links" being found in crates which aren't using intra-doc links at all. This, combined with the fact that we emit a proper warning lint for these resolution errors, led to situations where innocent crates suddenly broke because they had set. To be honest, running this without a proper feature gate is shaky, in terms of how unstable features work in the rest of the compiler and rustdoc, but until recently i was uncertain if we could properly introduce a gate to the compiler without a matching use in rustc itself. (All the attributes that rustdoc currently uses are tied to attributes, so their check code is also in the compiler.) I would be willing to introduce a feature gate for this, since it would also stamp down on the false positive rate across the ecosystem. However, it leads to similar broken-link situations. Imagine crate A which uses intra-doc links, complete with having the feature set. Now imagine crate B, which re-exports items from crate A to inline them into its own documentation, but doesn't use intra-doc links itself. Because crate B doesn't have the feature set, now those links from the crate A items won't resolve, even if they were accidentally correct because those items were re-exported into the right positions! (This situation exists today; these crates are and , though the items from that re-exports don't have any links on them.) I'm very hesitant to "partially stabilize" these links, because of the subtleties with re-exports that mentioned. It's too easy to use any part of this feature and get it to a position where it doesn't work. And the major hurdle for making that work requires a deep compiler refactor that is hard to find a champion for. If it comes down to it, if there is another Rust All-Hands early next year like the one in Berlin earlier this year, i may try getting the right people in a room together to design this problem out. However, that won't be able to happen for another few months.
I wonder if the standard library crates will need special treatment by this feature? For example, the link to the constant in docs needs to resolve to or depending if the docs are being rendered as part of the libstd or liballoc docs.
Small bug report (let me know if this isn't the correct place to report this): Currently, intra-doc links respect in a way that I'm not sure that they should. It means that simple links like fail to link to the correct place in the standard library documentation.
Well, it's part of the issue indeed. I'll add a bullet point for it.
The problem is that we use the same resolver that the compiler has made - which means that it's affected by . To universally load in libstd for intra-doc links, we either need to totally ignore when building docs (which may cause erroneous compilation errors) or have some way to find and load libstd's information (and prelude, since you mentioned specifically) after rustdoc takes over from the compiler. I'm sure it's possible, but it's more cumbersome than it seems.
It definitely seems like one of those cases where what is technically correct and what is expected are different, and we should design in favor of the latter. The easiest stopgap solution I can see would be to add a new compiler attribute, , so that users can write:
Do I get it right that , , are not supported for path resolution? does not seem to throw a warning of failed resolution where the other two do. However it creates a link as: which obviously doesn't work.
Hmm, they should work, but I think the implementation is buggy around them right now. On Tue, Apr 30, 2019, 7:18 AM Naja Melan <:
Ok, we do seem to have success with actually, but is definitely broken.
I didn't see it mention in the RFC or this issue, but is there a way to link to a documentation header in another crate? For example, I'd like to link to the syntax header of the regex crate. I can do something like this: But not something like this (which would be preferred, as that would link to the correct version of the syntax documentation):
No, intra doc links doesn't currently support linking to sections. It could. It doesn't support linking to other either, but that's trickier to get right.
What do you mean by this? Quick testing shows that intra-rustdoc links works fine with locally available docs, or specified in a dependency, or overrides on the command line. If you're referring to the fact there's no default external doc location when isn't set, that is independent of the intra-rustdoc feature, it will presumably just work if is updated to be able to default that.
I mean the general case of linking to an external crate on if it's not a dependency of yours or you are not on
Ok, so just , which applies to all links to external documentation including intra-rustdoc links.
I filed , in which the "module disambiguator does not seem to be respected.
I filed to propose support for linking to sections, [link text][MyStruct#my-section].
I filed about recognizing as an intra doc link.
I'm not fan of such things... For instance, what should we do with Vec<StringVecStringSomeType<T, U, V`".
I would be on board with linking if and only if the type parameters in the link match the names of the type's generic parameters, for example would get linked but would not.
That'd force to check all the generic parameters, not very ideal...
Would you be able to clarify what is not ideal about checking generic parameters? Is it difficult to implement? If that's the only thing, would you consider accepting a PR that takes care of the implementation?
No it's not difficult. It's just not ideal because it creates additional rules that I find useless. The goal of a feature is to be simple enough to let users use it without having to wonder: it something I can do? will be the outcome? In this case, we can consider that the first point wouldn't be an issue but the second definitely would.
It would be great if there were better support for rendering this style of linking then, currently they have weird spacing, opened about it.
While this is unstable it should at least produce warnings with non-nightly compilers to avoid catching users off-guard: Opened as
I see that has been merged to add support for primitive types, however I'm trying to link to as well, to test if it's just polymorphic primitives, and it seems that might be the issue, since it also doesn't work as a intra-link. Am I missing something?
It's still very unstable and experimental. A lot remains to be done. Can you open an issue about it and cc me on it please?
Would it be possible to have this resolve links to trait implementation? For example:
Normally it should work as is. But like said above, it's still very experimental.
It doesn't seem to work for me... on
This comment isn't very helpful... Can you provide us details like the markdown, the context, etc... ?
Fully reproducible example:
So, trait methods aren't working. Thanks for the feedback. Adding it to the points.
I filed to have the disambiguator stripped from the link text in something like .
Is there any centralised documentation for how exactly this feature works, considering how it's changed so much from the initial RFC? Like, specifically document what kinds of links should work and which shouldn't, and if parts of the text are removed from the final result? Like, I get that it's not going to be stabilised any time soon, but many folks use this feature and it's hard to reason which things work and which don't at the moment.
The only thing blocking stabilization now is
Isn't documentation also a blocker?
That's usually a part of stabilization.
Is there any way to hide any prefix when linking to types not within the current module and not in scope when using shorthand links? I notice in some of my documentation, I have some types imported, and can link to them using MyStructcrate::OtherStruct`, which looks a bit off in the documentation. I realise I can name the link whatever I want and then turn it into an actual link later by adding a reference, but that increases the bloat of the comment in the code itself. I guess it's a minor thing, and there's no clean way to solve this that isn't probably at least somewhat surprising to some, but I wanted to mention it nonetheless.
Have you tried something like:
One way that I tend to do this is using the (currently unstable, but pending stabilisation in ) . i.e., at the top of the file, I put: and then you can reference the type without the prefix. You can do this without the by simply adding , although I prefer the former as it will still lint if you don't actually use the import.
Could someone in the know please file an issue around "Handle fields inside struct variants" so that I know what might be needed in order to close off that blocker?
It's not a blocker. It's about giving the ability to link directly to a struct field by naming it in the link.
Isn't that ambiguous when there is also an inherent method with the same name? It's also "syntactically unnatural" to refer to struct fields in this way, though I can't think of a better way right now.
Yeah, that's why there's no issue for it, it's something we may want to add and if we do we'd have to figure out how. It's not a blocker. Thanks, -Manish Goregaokar Mikhail Zabaluev <:
Aha, thanks. I misunderstood the presence of something in the top comment with a tickybox as being something which had to be done. Is there an issue capturing the desire to link to a struct's field so that it doesn't get lost if this issue is closed? Or is there a process for splitting out remaining issues when we close a tracking issue?
We can file an issue now if you want, but basically any leftover non blockers will be filed as issues once this is closed. On Sat, Nov 9, 2019, 11:23 PM Daniel Silverstone <:
Okay, if raising issues when this closes is the process then that's perfect. I'm not in a rush to have that issue, I was just trying to properly understand (a) what was actually considered blocking for stabilisation, and (b) what the process was to deal with remaining things if it wasn't all blocking. Thank you for clarifying things
Cross crate imports and documentation are the only stabilization blockers AIUI. Documentation can be done during the stabilization process.
If someone wants to add docs earlier they can be to the unstable book, and then moved over to the reference.
seems like has a similar thing in progress at for
See also:
Oooh interesting, thank you. I shall have to have a look when gets closer to completion. I have plenty to be doing before I try for the better resolution, so if their work makes life easier for us, then that's excellent.
You should coordinate with them and see if there's a way y'all can work together! It's possible their work is already sufficient for your purposes here. On Sun, Nov 10, 2019, 11:52 PM Daniel Silverstone <:
When I tried using intra-doc links in libstd docs a few months ago, I was told they are still experimental and should not be used yet. What is the current status? When writing new docs / adding new links to existing docs, should I use intra-doc links?
Would it be possible to land the current intra-doc feature without cross crate imports? That would hit most of my needs for intra-doc resolution and still leaves open the option to land cross-crate imports later.
The problem is that anyone might re-export a type from your crate and then the documentation will be broken.
So the user of the feature can't know in advance when it will break. I guess we could still stabilize it with this caveat and request people to work with upstream authors to remove these links when reexporting.
If you're targetting docs built by it should be "fine". But as long as we don't have everything fixed, I don't think this is a good idea to stabilize it yet.
I don't if this is already on someone's radar but, linking to re-exported macros doesn't work at the moment. Simple test case: In : It fails with the following: Versions: rustc 1.43.0-nightly ( 2020-03-08) cargo 1.43.0-nightly ( 2020-03-02)
this is
This should be fixed now. See issue, MR,
Perhaps this is fixed now, see issue: MR: If not please. please provide a minimal example for it to clarify it.
I don't understand how to link to a re-exported procedural macro. The RFC indicates that linking to a macro is possible, but none of my attempts appear to successfully link. the- the-
the re-export is the problem, see As a workaround, you might be able to use the absolute path (), but I haven't tested that.
Yeah, that was one I tried in my project but didn't reflect in the reproduction. It didn't seem to work either. <details<summaryAttempts</summary</details
I'm not sure, right now cross-doc links are pretty broken. Hopefully will land in the next few weeks, you could try again afterwards.
the cross crate bug is unrelated to the one being described by You should totally be able to link to a in the current implementation, so what describes is an independent bug
Can confirm that linking to works, but not if it's a proc macro being used. Macro scoping is weird so that's probably it.
Oh, this has nothing to do with pub use, we're just completely incapable of linking to derive macros
Filed , thanks
Note: once lands all of the blocker issues for this will have resolved and we should be a go for stabilizing the feature with docs. Note that it has baked as nightly-only for ages now.
I'll write documentation once it's merged then. We still have a few other points which need to be solved before stabilization though, but we're getting close! :)
I haven't had time to make a minimal repro, but there still appears to be an issue with linking to free-functions on cross-crate inlined docs like even using the from .
I've already got some of the docs written. It's not clear to me if the remaining issues should block stabilization, I think they can be treated as just another bug. We don't typically block stabilization on minor bugs whose fix will not impact the feature.
Do we have a general consensus on what kinds of changes are considered major or minor when it comes to doc syntax?
I don't think there are or needs to be rigid rules around that. When a feature is considered for stabilization, the relevant team looks at the status of the feature, and decides if it's ready. Like I said, typically bugs where the fix is not likely to severely change the feature are okay to have. In this case the major blocker, the cross-crate issue, was one where we weren't even sure if it was possible to implement, and it might have changed how the feature worked. It was also just a major piece of functionality. The current remaining issues are linking to std: this is a quality of life improvement where you can still link to items from a crate. The other one is about linking to the docs of the slice primitive, which is also a quality of life improvement, since people do that rarely.
I don't think there need to be strict rules, but I was mostly asking because I figure that this might come up more as rustdoc becomes more robust and changes to its syntax can throw deny-by-default warnings. My general assumption is that regardless of whether something might "break" that docs are considered separate enough to ignore these issues in favour of pushing out changes sooner, but I figure that a potential clarification on that might be helpful to avoid this confusion in the future.
oh that's fair. When it comes to lints the general Rust stabilty model is that new warn-by-default lints are always okay, deny-by-default lints should usually go through some cycles of warn-by-default unless there are special circumstances.
Okay, so I've narrowed bug down to the check in failing. Removing that line lets the link work just fine.
Annoyingly, any attempt to narrow down the testcase is failing for me. What's happening though is that the defid is absent from the accesslevels map. I'm not sure why.
Aha, it's the . Moving that to the end of the file fixes the issue . I'll try to file a bug about this.
FWIW the following part doesn't seem to occur anymore. This might have been an issue during the edition changes to resolution
Removing the no_std issue in the list because is actually a broader rustdoc bug
FWIW, I support stabilizing even with the remaining bugs. This flag is already used pervasively, for example, I believe all of uses this.
There's a WIP PR implementing resolving intra-rustdoc links, and traditional path-based links, in rust-analyzer .
That's really great, thanks!
Should we add suggestions to part of the tracking issue? For example, Could be Or we could guide them to do (I personally am not sure how to do this, I wish I could help out with diagnostics )
I think this should be a separate issue, it shouldn't block stabilizing the feature.
File a separate issue. Also the diagnostics here should be to suggest IMO.
I think it's a fair bit more involved to introduce this diagnostic fwiw
Status update: All the code for this has been written (that I know of), it's just waiting on a very long PR trail: -Once that is done, we can make a stabilization PR . The beta release is on Tuesday, which this will most likely miss; if it miraculously makes Tuesday we'll delay stabilization until afterwards because makes a lot of internal changes and should see a full 6 weeks on nightly before making it to beta. Additionally I'd love to see merged before since I expect it to improve rustdoc's performance quite a lot. That shouldn't block intra-doc links, though. EDIT: this landed
feel free to include in btw, we can land both at once
I'd rather not, is a good change even if we have to revert . Also it can be rolled-up and shouldn't be.
Once that is done we'll have an initial functional implementation. The next step is testing it. A big part of that will be to start using it in the docs and seeing if it can fix the issues it was designed for (, ).
We have had a functional implementation for three years now. It has been used in the stdlib docs for ages, and is used across the ecosystem. The ability for reexports to work correctly was a blocker to stabilization, but it is not a huge feature that will be used a lot. The reason stabilization was blocked on reexports was that we determined that the bug fix could be complicated and might require rearchitecting the feature, which made us reluctant to stabilize earlier.
I hadn't seen these issues earlier, and we should absolutely fix them using intra doc links, but I don't want to block stabilization on that. We've had this feature mostly working for ages.
Alright, so the current status of this is that we have a stack of PRs blocking all remaining major issues (, ): - - - Between and myself, we hope to stabilize this shortly thereafter. will be filing an FCP but as we're currently mostly waiting for the final chips to fall in place, I wanted to front-load some of the discussions that may happen during that FCP. Hopefully when we make that FCP it is simply some rubber-stamping if we have these discussions earlier. What are your thoughts on stabilizing this shortly after the last few patches land? I recall having some concerns. I don't recall if has said anything on this point. My position on this (I think this is shared by Guillaume and Joshua) is that this feature has been cooking on nightly for three years now. The cross-crate import issue was a blocker not because it was a major piece of functionality, but rather because there was a chance we wouldn't be able to implement it in a neat manner and would paint ourselves into a corner by committing to it. It's clear that that's not the case. If we're worried about the code for cross-crate imports itself being broken, that's what the release train schedule is for -- we can undo these patches and stabilization for twelve weeks if this happens.
I think that once the remaining stack lands, we're in good shape to stabilise. There're bound to be corner cases we've not found etc. and documentation which could be improved, but getting this out and usable by the general developer community will be immensely useful.
has landed, so now we're ready for stabilization. should land soon
Stabilization PR is ready
After this is no longer the case. Should the RFC be updated?
go for it
Triage: has been merged, so its mark can be checked, I believe?
Hi, does someone knows how to write intra-rustdoc links to ? I'm not sure if this is not implemented or if I'm writing incorrectly. Have tried those, but they are not working:

}; pub fn collect_intra_doc_links(krate: Crate, cx: &DocContext<'_>) -> Crate { <del> if !UnstableFeatures::from_environment().is_nightly_build() { krate } else { let mut coll = LinkCollector::new(cx); coll.fold_crate(krate) } </del> <ins> let mut coll = LinkCollector::new(cx); coll.fold_crate(krate) </ins> } enum ErrorKind<'a> {


Question:
After discussing it on the forums I bit I decided to look into what the optimizer spends time on, and inlining seems to be a significant part of it. There seems to be a lot of room for improvement here. Tested by compiling syntex in rustc-benchmarks (though the inlining time seem quite significant in other crates as well.). I counted which functions were inlined the most, and and to a lesser extent , which are when automatically deriving , and which simply wrap two other functions inside fmt::builder show up a lot. Maybe derive(debug) could output the wrapped functions instead, or the equivalent code, so llvm doesn't have to spend time inlining them (unless this causes problems for debug info). is also inlined a lot, and also plays a role in derive(Debug). Maybe something could be done about that one as well, as it's that creates a struct but doesn't do anything else. <details<summaryOutput from time-llvm-passes</summaryUsing in the syntex-0.42.2 directory in rustc-benchmarks. It's a bit hard to say which crate is which, as the output from llvm and cargo isn't synced, though these are the bottom three (excluding the benchmark dummy) in reverse order: </details<details<summaryMost inlined functions: </summaryRunning , and filtering the output using this: (Yeah it's a bit of a monstrosity, and takes a long time, maybe I could look into making some tool analyze this if it turns out to be useful.) gives: <pre1865 ZN4core3ptr13dropinplace17hffb7ed55089717f8E inlined into 917 ZN50Tascore..convert..FromTGT$4from17h99c56b7d2123957eE inlined into <b677 ZN4core3fmt9Arguments6newv117h0a32116e8ade096aE inlined into</b549 ZN4core3ptr13dropinplace17h8905708a4bea3261E inlined into <b517 ZN4core3fmt9Formatter11debugtuple17h312acfb009988478E inlined into</b484 ZN50Tascore..convert..FromTGT$4from17hf6536c6dc214691bE inlined into 438 ZN5alloc9allocator6Layout4size17h278602cb6317171dE inlined into 402 ZN63alloc..allocator..LayoutasGT$5clone17hba86f6db001903cdE inlined into 381 ZN61u20u20GT$7dealloc17h3db9762b4fdfd21eE inlined into 344 ZN5alloc4heap15exchangemalloc17he9800f033a6330e4E inlined into 341 ZN4core3ptr13dropinplace17hb5325e51b98a161aE inlined into ... <b82 ZN4core3fmt9Formatter12debug_struct17h5cfb920e90696799E inlined into</b... </pre</details<details<summaryrustc --version</summary</details
We should just drop the from those functions - debug printing is something we want to be optimizing on code size/compile time rather than perf.
Yup, that's a good point. EDIT: Actually since they're just generic over lifetimes it looks like that's not an issue.

/// println!("{:?}", Foo { bar: 10, baz: "Hello World".to_string() }); /// ``` #[stable(feature = "debug_builders", since = "1.2.0")] <del> #[inline] </del> pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a> { builders::debug_struct_new(self, name) }


Question:
After discussing it on the forums I bit I decided to look into what the optimizer spends time on, and inlining seems to be a significant part of it. There seems to be a lot of room for improvement here. Tested by compiling syntex in rustc-benchmarks (though the inlining time seem quite significant in other crates as well.). I counted which functions were inlined the most, and and to a lesser extent , which are when automatically deriving , and which simply wrap two other functions inside fmt::builder show up a lot. Maybe derive(debug) could output the wrapped functions instead, or the equivalent code, so llvm doesn't have to spend time inlining them (unless this causes problems for debug info). is also inlined a lot, and also plays a role in derive(Debug). Maybe something could be done about that one as well, as it's that creates a struct but doesn't do anything else. <details<summaryOutput from time-llvm-passes</summaryUsing in the syntex-0.42.2 directory in rustc-benchmarks. It's a bit hard to say which crate is which, as the output from llvm and cargo isn't synced, though these are the bottom three (excluding the benchmark dummy) in reverse order: </details<details<summaryMost inlined functions: </summaryRunning , and filtering the output using this: (Yeah it's a bit of a monstrosity, and takes a long time, maybe I could look into making some tool analyze this if it turns out to be useful.) gives: <pre1865 ZN4core3ptr13dropinplace17hffb7ed55089717f8E inlined into 917 ZN50Tascore..convert..FromTGT$4from17h99c56b7d2123957eE inlined into <b677 ZN4core3fmt9Arguments6newv117h0a32116e8ade096aE inlined into</b549 ZN4core3ptr13dropinplace17h8905708a4bea3261E inlined into <b517 ZN4core3fmt9Formatter11debugtuple17h312acfb009988478E inlined into</b484 ZN50Tascore..convert..FromTGT$4from17hf6536c6dc214691bE inlined into 438 ZN5alloc9allocator6Layout4size17h278602cb6317171dE inlined into 402 ZN63alloc..allocator..LayoutasGT$5clone17hba86f6db001903cdE inlined into 381 ZN61u20u20GT$7dealloc17h3db9762b4fdfd21eE inlined into 344 ZN5alloc4heap15exchangemalloc17he9800f033a6330e4E inlined into 341 ZN4core3ptr13dropinplace17hb5325e51b98a161aE inlined into ... <b82 ZN4core3fmt9Formatter12debug_struct17h5cfb920e90696799E inlined into</b... </pre</details<details<summaryrustc --version</summary</details
We should just drop the from those functions - debug printing is something we want to be optimizing on code size/compile time rather than perf.
Yup, that's a good point. EDIT: Actually since they're just generic over lifetimes it looks like that's not an issue.

/// println!("{:?}", Foo(10, "Hello World".to_string())); /// ``` #[stable(feature = "debug_builders", since = "1.2.0")] <del> #[inline] </del> pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a> { builders::debug_tuple_new(self, name) }


Question:
After discussing it on the forums I bit I decided to look into what the optimizer spends time on, and inlining seems to be a significant part of it. There seems to be a lot of room for improvement here. Tested by compiling syntex in rustc-benchmarks (though the inlining time seem quite significant in other crates as well.). I counted which functions were inlined the most, and and to a lesser extent , which are when automatically deriving , and which simply wrap two other functions inside fmt::builder show up a lot. Maybe derive(debug) could output the wrapped functions instead, or the equivalent code, so llvm doesn't have to spend time inlining them (unless this causes problems for debug info). is also inlined a lot, and also plays a role in derive(Debug). Maybe something could be done about that one as well, as it's that creates a struct but doesn't do anything else. <details<summaryOutput from time-llvm-passes</summaryUsing in the syntex-0.42.2 directory in rustc-benchmarks. It's a bit hard to say which crate is which, as the output from llvm and cargo isn't synced, though these are the bottom three (excluding the benchmark dummy) in reverse order: </details<details<summaryMost inlined functions: </summaryRunning , and filtering the output using this: (Yeah it's a bit of a monstrosity, and takes a long time, maybe I could look into making some tool analyze this if it turns out to be useful.) gives: <pre1865 ZN4core3ptr13dropinplace17hffb7ed55089717f8E inlined into 917 ZN50Tascore..convert..FromTGT$4from17h99c56b7d2123957eE inlined into <b677 ZN4core3fmt9Arguments6newv117h0a32116e8ade096aE inlined into</b549 ZN4core3ptr13dropinplace17h8905708a4bea3261E inlined into <b517 ZN4core3fmt9Formatter11debugtuple17h312acfb009988478E inlined into</b484 ZN50Tascore..convert..FromTGT$4from17hf6536c6dc214691bE inlined into 438 ZN5alloc9allocator6Layout4size17h278602cb6317171dE inlined into 402 ZN63alloc..allocator..LayoutasGT$5clone17hba86f6db001903cdE inlined into 381 ZN61u20u20GT$7dealloc17h3db9762b4fdfd21eE inlined into 344 ZN5alloc4heap15exchangemalloc17he9800f033a6330e4E inlined into 341 ZN4core3ptr13dropinplace17hb5325e51b98a161aE inlined into ... <b82 ZN4core3fmt9Formatter12debug_struct17h5cfb920e90696799E inlined into</b... </pre</details<details<summaryrustc --version</summary</details
We should just drop the from those functions - debug printing is something we want to be optimizing on code size/compile time rather than perf.
Yup, that's a good point. EDIT: Actually since they're just generic over lifetimes it looks like that's not an issue.

/// println!("{:?}", Foo(vec![10, 11])); /// ``` #[stable(feature = "debug_builders", since = "1.2.0")] <del> #[inline] </del> pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a> { builders::debug_list_new(self) }


Question:
After discussing it on the forums I bit I decided to look into what the optimizer spends time on, and inlining seems to be a significant part of it. There seems to be a lot of room for improvement here. Tested by compiling syntex in rustc-benchmarks (though the inlining time seem quite significant in other crates as well.). I counted which functions were inlined the most, and and to a lesser extent , which are when automatically deriving , and which simply wrap two other functions inside fmt::builder show up a lot. Maybe derive(debug) could output the wrapped functions instead, or the equivalent code, so llvm doesn't have to spend time inlining them (unless this causes problems for debug info). is also inlined a lot, and also plays a role in derive(Debug). Maybe something could be done about that one as well, as it's that creates a struct but doesn't do anything else. <details<summaryOutput from time-llvm-passes</summaryUsing in the syntex-0.42.2 directory in rustc-benchmarks. It's a bit hard to say which crate is which, as the output from llvm and cargo isn't synced, though these are the bottom three (excluding the benchmark dummy) in reverse order: </details<details<summaryMost inlined functions: </summaryRunning , and filtering the output using this: (Yeah it's a bit of a monstrosity, and takes a long time, maybe I could look into making some tool analyze this if it turns out to be useful.) gives: <pre1865 ZN4core3ptr13dropinplace17hffb7ed55089717f8E inlined into 917 ZN50Tascore..convert..FromTGT$4from17h99c56b7d2123957eE inlined into <b677 ZN4core3fmt9Arguments6newv117h0a32116e8ade096aE inlined into</b549 ZN4core3ptr13dropinplace17h8905708a4bea3261E inlined into <b517 ZN4core3fmt9Formatter11debugtuple17h312acfb009988478E inlined into</b484 ZN50Tascore..convert..FromTGT$4from17hf6536c6dc214691bE inlined into 438 ZN5alloc9allocator6Layout4size17h278602cb6317171dE inlined into 402 ZN63alloc..allocator..LayoutasGT$5clone17hba86f6db001903cdE inlined into 381 ZN61u20u20GT$7dealloc17h3db9762b4fdfd21eE inlined into 344 ZN5alloc4heap15exchangemalloc17he9800f033a6330e4E inlined into 341 ZN4core3ptr13dropinplace17hb5325e51b98a161aE inlined into ... <b82 ZN4core3fmt9Formatter12debug_struct17h5cfb920e90696799E inlined into</b... </pre</details<details<summaryrustc --version</summary</details
We should just drop the from those functions - debug printing is something we want to be optimizing on code size/compile time rather than perf.
Yup, that's a good point. EDIT: Actually since they're just generic over lifetimes it looks like that's not an issue.

/// println!("{:?}", Foo(vec![10, 11])); /// ``` #[stable(feature = "debug_builders", since = "1.2.0")] <del> #[inline] </del> pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a> { builders::debug_set_new(self) }


Question:
After discussing it on the forums I bit I decided to look into what the optimizer spends time on, and inlining seems to be a significant part of it. There seems to be a lot of room for improvement here. Tested by compiling syntex in rustc-benchmarks (though the inlining time seem quite significant in other crates as well.). I counted which functions were inlined the most, and and to a lesser extent , which are when automatically deriving , and which simply wrap two other functions inside fmt::builder show up a lot. Maybe derive(debug) could output the wrapped functions instead, or the equivalent code, so llvm doesn't have to spend time inlining them (unless this causes problems for debug info). is also inlined a lot, and also plays a role in derive(Debug). Maybe something could be done about that one as well, as it's that creates a struct but doesn't do anything else. <details<summaryOutput from time-llvm-passes</summaryUsing in the syntex-0.42.2 directory in rustc-benchmarks. It's a bit hard to say which crate is which, as the output from llvm and cargo isn't synced, though these are the bottom three (excluding the benchmark dummy) in reverse order: </details<details<summaryMost inlined functions: </summaryRunning , and filtering the output using this: (Yeah it's a bit of a monstrosity, and takes a long time, maybe I could look into making some tool analyze this if it turns out to be useful.) gives: <pre1865 ZN4core3ptr13dropinplace17hffb7ed55089717f8E inlined into 917 ZN50Tascore..convert..FromTGT$4from17h99c56b7d2123957eE inlined into <b677 ZN4core3fmt9Arguments6newv117h0a32116e8ade096aE inlined into</b549 ZN4core3ptr13dropinplace17h8905708a4bea3261E inlined into <b517 ZN4core3fmt9Formatter11debugtuple17h312acfb009988478E inlined into</b484 ZN50Tascore..convert..FromTGT$4from17hf6536c6dc214691bE inlined into 438 ZN5alloc9allocator6Layout4size17h278602cb6317171dE inlined into 402 ZN63alloc..allocator..LayoutasGT$5clone17hba86f6db001903cdE inlined into 381 ZN61u20u20GT$7dealloc17h3db9762b4fdfd21eE inlined into 344 ZN5alloc4heap15exchangemalloc17he9800f033a6330e4E inlined into 341 ZN4core3ptr13dropinplace17hb5325e51b98a161aE inlined into ... <b82 ZN4core3fmt9Formatter12debug_struct17h5cfb920e90696799E inlined into</b... </pre</details<details<summaryrustc --version</summary</details
We should just drop the from those functions - debug printing is something we want to be optimizing on code size/compile time rather than perf.
Yup, that's a good point. EDIT: Actually since they're just generic over lifetimes it looks like that's not an issue.

/// println!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])); /// ``` #[stable(feature = "debug_builders", since = "1.2.0")] <del> #[inline] </del> pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a> { builders::debug_map_new(self) }


Question:
In the following scenario, the user will have a better experience if we allow them to have an "unused" extern crate. If we permit them to write , as recommended by Serde's docs for this reason, the error message is: If they remove the unused , they generally get nastier error messages. If we can't fix the error message to be as good as it was before the unusedexterncrates warning, let's disable unusedexterncrates in cases where the same crate is used later in some nested scope (submodule or code block). cc who has been involved with this warning.
Arguable point. As the statement doesn't impact the binary (linkage), it doesn't harm if we disabled the lint. I'm not sure about the way to implement it though.
the above example works now without the requirement of . Is there anything else blocking this other than ?
Closing this as the error case is the same now irrespective of whether extern crate is included or not.
There is still a minor improvement from adding . Less bad compared to though.

declare_lint! { pub UNUSED_EXTERN_CRATES, <del> Warn, </del> <ins> Allow, </ins> "extern crates that are never used" }


Question:
Was looking at the printout of llvm passes when I noticed that the functions that was inlined everywhere, and due to this was dead code, was optimized more after inlining. So as a test I at the line and this reduces the compile time of release build in racer by an average of 23%. I do not know if this is a good place to add this extra pass but maybe someone that knows how llvm works can use this information to speedup the compilation of release builds. was also wondering how this works in MIR I see that there is an inline pass but I can not find any dead code elimination
the stage1 compilation of rustc went from 828.89 to 691.75 secs with this fix on my computer but that is only a 15% improvement
15% is pretty significant.
Wow, great work!
That's some nice improvements! If you feel up to it, go ahead an submit a pull request with your suggested changes. That way someone with experience with LLVM is guaranteed to look at the patch and it won't get lost.
I believe the PR should be targeted at
:+1: If you want to push through this patch the general process works like this: Submit the patch against the currently active branch of (which is at the moment) Wait for it to get reviewed & merged Submit a pull request against which updates the submodule. If you have any questions about the process or want someone else to do this, just mention it here or contact me or someone else on one of the .
cc
cc
Ideally, the process should include discussion with upstream LLVM too.
Unfortunately it looks like we were a bit too eager to close this in :(
From what I have learned from the llvm maintainers I think that we have received the improvement that can be expected. The to good to be true improvements I measured was probably due to less optimizations was possible and resulted in less optimized code.

<del> Subproject commit d9e7d2696e41983b6b5a0b4fac604b4e548a84d3 </del> <ins> Subproject commit c7a16bd57c2a9c643a52f0cebecdaf0b6a996da1 </ins>


Question:
The standard library provides a way to get the process id of a child process with , but doesn't have any way to get the current processes id (the equivalent of ). It is possible to do this with , but it seems to me that this should be something that is part of the standard library, especially since it already has cross-platform support for process ids of child processes.
Seems reasonable to add!
on Windows.
Reopening as the tracking issue.
While porting Rust over to , a sandboxed UNIX-like runtime environment, I ran into the issue that there is no way for me to implement this function. As we're aiming to use CloudABI in distributed settings, there is no traditional 16/32-bit process identifier. Instead, processes may be identified by a UUID. This is useful, as integer process identifiers can easily collide when dealing with many instances of a job (due to the birthday paradox). As this function was only introduced recently, would it still be possible to alter it to return an opaque, but displayable data type instead? That said, almost all of the other functions provided by this module are also broken on CloudABI. The traditional model doesn't lend well to sandboxing. Maybe it makes more sense to disable on CloudABI entirely.
I'm opposed a completely opaque data type, because that limits the usefulness. For example, that makes it difficult to use in C (or dbus) that require a PID. However, I think it would be alright if the it was a semi-opaque type with OS-specific API's to get the underlying representation (in std::os::unix, etc). However, that would break consistency with , which is already stabilized. I'm not sure how you would deal with that either.
As has mentioned, the ship has already sailed here due to . More generally, though. I'm not sure it makes sense to avoid supporting getpid of all things because some platform decided not to implement it.
One thing that would be low-hanging fruit would be to at least have some kind of type alias for this. On UNIX/Windows, it could be defined as . On CloudABI, it could be a string. That way, existing code that uses continues to build on existing platforms, whereas less conventional platforms can choose to implement this function differently.
Given this: and this: I’m inclined to stabilize as-is. (Returning .) fcp merge Hopefully the can eventually help a CloudABI port to "cleanly" implement this differently, or not at all.
Team member has proposed to merge this. The next step is review by the rest of the tagged teams: [x] [x] [x] [x] [x] [x] [ ] No concerns currently listed. Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See for info about what commands tagged team members can give me.
:bell: This is now entering its final comment period, as per the . :bell:
The final comment period is now complete.

unsafe { ::sys::abort_internal() }; } <ins> /// Returns the OS-assigned process identifier associated with this process. /// /// # Examples /// /// Basic usage: /// /// ```no_run /// #![feature(getpid)] /// use std::process; /// /// println!("My pid is {}", process::id()); /// ``` /// /// #[unstable(feature = "getpid", issue = "44971", reason = "recently added")] pub fn id() -> u32 { ::sys::os::getpid() } </ins> #[cfg(all(test, not(target_os = "emscripten")))] mod tests { use io::prelude::*;


Question:
The standard library provides a way to get the process id of a child process with , but doesn't have any way to get the current processes id (the equivalent of ). It is possible to do this with , but it seems to me that this should be something that is part of the standard library, especially since it already has cross-platform support for process ids of child processes.
Seems reasonable to add!
on Windows.
Reopening as the tracking issue.
While porting Rust over to , a sandboxed UNIX-like runtime environment, I ran into the issue that there is no way for me to implement this function. As we're aiming to use CloudABI in distributed settings, there is no traditional 16/32-bit process identifier. Instead, processes may be identified by a UUID. This is useful, as integer process identifiers can easily collide when dealing with many instances of a job (due to the birthday paradox). As this function was only introduced recently, would it still be possible to alter it to return an opaque, but displayable data type instead? That said, almost all of the other functions provided by this module are also broken on CloudABI. The traditional model doesn't lend well to sandboxing. Maybe it makes more sense to disable on CloudABI entirely.
I'm opposed a completely opaque data type, because that limits the usefulness. For example, that makes it difficult to use in C (or dbus) that require a PID. However, I think it would be alright if the it was a semi-opaque type with OS-specific API's to get the underlying representation (in std::os::unix, etc). However, that would break consistency with , which is already stabilized. I'm not sure how you would deal with that either.
As has mentioned, the ship has already sailed here due to . More generally, though. I'm not sure it makes sense to avoid supporting getpid of all things because some platform decided not to implement it.
One thing that would be low-hanging fruit would be to at least have some kind of type alias for this. On UNIX/Windows, it could be defined as . On CloudABI, it could be a string. That way, existing code that uses continues to build on existing platforms, whereas less conventional platforms can choose to implement this function differently.
Given this: and this: I’m inclined to stabilize as-is. (Returning .) fcp merge Hopefully the can eventually help a CloudABI port to "cleanly" implement this differently, or not at all.
Team member has proposed to merge this. The next step is review by the rest of the tagged teams: [x] [x] [x] [x] [x] [x] [ ] No concerns currently listed. Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See for info about what commands tagged team members can give me.
:bell: This is now entering its final comment period, as per the . :bell:
The final comment period is now complete.

let _ = syscall::exit(code as usize); unreachable!(); } <ins> pub fn getpid() -> u32 { syscall::getpid().unwrap() as u32 } </ins>