Add missing type links in documentation #62120
Conversation
rust-highfive
added
the
S-waiting-on-review
This comment has been minimized.
This comment has been minimized.
src/libcore/pin.rs
Outdated
| //! operations such as [`mem::swap`]: | ||
| //! and common smart-pointer types such as [`Box<T>`] and `&mut T` allow replacing and | ||
| //! moving the values they contain: you can move out of a [`Box<T>`], or you can use | ||
| //! [`mem::swap`]. [`Pin<P>`] wraps a pointer type `P`, so [`Pin`]`<`[`Box<T>`]`>` functions much |
There was a problem hiding this comment.
It would be nice if intra docs understood the concept of a type constructor and gave you two links automatically.
There was a problem hiding this comment.
Type constructor? You're talking about Pin<Box<T>> I guess? If so, we can't be sure you want two links or just one. :)
There was a problem hiding this comment.
Two links, one to Pin and one to Box. We don't want a link to T because it's a type variable (well... it might be useful actually...).
There was a problem hiding this comment.
It *could*, we can't guess it automatically unfortunately.
There was a problem hiding this comment.
@GuillaumeGomez Can you not use resolution info check whether T comes from a type variable? For Pin<Box<T>> we can at least determine syntactically that Pin and Box are type constructors and that Pin, Box, and T are separate entities.
There was a problem hiding this comment.
Yes but we can't be sure we're referring to an actual type or not something we just made up in the explanation two lines ago. :-/
GuillaumeGomez
force-pushed
the
add-missing-type-links
branch
from
14b20f0 to
a495a46
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
GuillaumeGomez
force-pushed
the
add-missing-type-links
branch
7 times, most recently
from
7f5df23 to
3a5eb6e
Compare
GuillaumeGomez
force-pushed
the
add-missing-type-links
branch
from
3a5eb6e to
c8aa3c1
Compare
|
@rust-lang/docs I'm starting to question the utility of having every single reference to some type have a hyperlink. If something was linked the first time it was mentioned, what's the use of linking it four times in the same paragraph? It's starting to feel like it's just adding noise to the docs and extra bytes to the page size. This PR still seems like it introduces some new type links, so it's still somewhat useful, but paragraphs that have three links to |
I am in agreement with this guideline (whether I follow it or not is a different question...). How outrageous would it be for rustdoc to enforce it? That is, only use the first unique (link text, URL) pair in some container (say inside a { |
|
I prefer adding links for every types for a few reasons:
For those reasons, it seems good to me to make link for every appearance of a type that isn't |
|
ping from triage @Centril, any updates on this? |
|
I'm in agreement with @GuillaumeGomez about the utility here. While it might not be as aesthetically pleasing, the functionality / utility provided by links is more important. If you disagree feel free to unapprove. |
|
📌 Commit c8aa3c1 has been approved by |
bors
added
S-waiting-on-bors
…ks, r=Centril Add missing type links in documentation r? @rust-lang/docs
…ks, r=Centril Add missing type links in documentation r? @rust-lang/docs
Rollup of 22 pull requests Successful merges: - #62084 (allow clippy::unreadable_literal in unicode tables) - #62120 (Add missing type links in documentation) - #62310 (Add missing doc links in boxed module) - #62421 (Introduce `as_deref` to Option) - #62583 (Implement Unpin for all raw pointers) - #62692 (rustc: precompute the largest Niche and store it in LayoutDetails.) - #62801 (Remove support for -Zlower-128bit-ops) - #62828 (Remove vector fadd/fmul reduction workarounds) - #62862 (code cleanup) - #62904 (Disable d32 on armv6 hf targets) - #62907 (Initialize the MSP430 AsmParser) - #62956 (Implement slow-path for FirstSets::first) - #62963 (Allow lexer to recover from some homoglyphs) - #62964 (clarify and unify some type test names) - #62970 (ci: gate toolstate repo pushes on the TOOLSTATE_PUBLISH envvar) - #62980 (std: Add more accessors for `Metadata` on Windows) - #62983 (Remove needless indirection through Rc) - #62985 (librustc_errors: Support ui-testing flag in annotate-snippet emitter) - #63002 (error_index_generator should output stdout/stderr when it panics.) - #63004 (Add test for issue-54062) - #63007 (ci: debug network failures while downloading awscli from PyPI) - #63009 (Remove redundant `mut` from variable declaration.) Failed merges: r? @ghost
r? @rust-lang/docs