| Age | Commit message (Collapse) | Author | Lines |
|---|
|
|
|
|
|
Look at this beauty:
```rust
error: unresolved link to `S::h`
--> intra-link-errors.rs:51:6
|
51 | /// [type@S::h]
| ^^^^^^^^^ help: to link to the associated function, use its disambiguator: `S::h()`
|
= note: this link resolves to the associated function `h`, which is not in the type namespace
```
|
|
|
|
|
|
|
|
Fix intra-doc links on pub re-exports
Partial fix for https://github.com/rust-lang/rust/issues/76073 - This removes the incorrect error, but doesn't show the documentation anywhere.
r? @GuillaumeGomez
|
|
Remove disambiguators from intra doc link text
Closes https://github.com/rust-lang/rust/issues/65354.
r? @Manishearth
The commits are mostly atomic, but there might be some mix between them here and there. I recommend reading 'refactor ItemLink' and 'refactor RenderedLink' on their own though, lots of churn without any logic changes.
|
|
|
|
- Preserve suffixes when displaying
- Rename test file to match `intra-link*`
- Remove unnecessary .clone()s
- Improve comments and naming
- Fix more bugs and add tests
- Escape intra-doc link example in public documentation
|
|
|
|
Related to https://github.com/rust-lang/rust/issues/65354
- Pass through the replacement text to `markdown.rs`
- Add some tests
- Add a state machine that actually replaces the text when parsing Markdown
|
|
|
|
|
|
Make `StringReader` private
r? @ghost
closes #75619
|
|
`parse_stream_from_source_str` is a more stable API to convert a
string into a bunch of tokens, and it also catches errors about
mismatched parenthesis.
|
|
|
|
around documenting re-exports
|
|
Fix intra-doc links for cross-crate re-exports of default trait methods
The original fix for this was very simple: https://github.com/rust-lang/rust/pull/58972 ignored `extern_traits` because before https://github.com/rust-lang/rust/issues/65983 was fixed, they would always fail to resolve, giving spurious warnings. So the first commit just undoes that change, so extern traits are now seen by the `collect_intra_doc_links` pass. There are also some minor changes in `librustdoc/fold.rs` to avoid borrowing the `extern_traits` RefCell more than once at a time.
However, that brought up a much more thorny problem. `rustc_resolve` started giving 'error: cannot find a built-in macro with name `cfg`' when documenting `libproc_macro` (I still haven't been able to reproduce on anything smaller than the full standard library). The chain of events looked like this (thanks @eddyb for the help debugging!):
0. `x.py build --stage 1` builds the standard library and creates a sysroot
1. `cargo doc` does something like `cargo check` to create `rmeta`s for all the crates (unrelated to what was built above)
2. the `cargo check`-like `libcore-*.rmeta` is loaded as a transitive dependency *and claims ownership* of builtin macros
3. `rustdoc` later tries to resolve some path in a doc link
4. suggestion logic fires and loads "extern prelude" crates by name
5. the sysroot `libcore-*.rlib` is loaded and *fails to claim ownership* of builtin macros
`rustc_resolve` gives the error after step 5. However, `rustdoc` doesn't need suggestions at all - `resolve_str_path_error` completely discards the `ResolutionError`! The fix implemented in this PR is to skip the suggestion logic for `resolve_ast_path`: pass `record_used: false` and skip `lookup_import_candidates` when `record_used` isn't set.
It's possible that if/when https://github.com/rust-lang/rust/issues/74207 is implemented this will need a more in-depth fix which returns a `ResolutionError` from `compile_macro`, to allow rustdoc to reuse the suggestions from rustc_resolve. However, that's a much larger change and there's no need for it yet, so I haven't implemented it here.
Fixes https://github.com/rust-lang/rust/issues/73829.
r? @GuillaumeGomez
|
|
|
|
Previously, only associated functions would be resolved.
|
|
#58972 ignored extern_traits because before #65983 was fixed, they
would always fail to resolve, giving spurious warnings.
This undoes that change, so extern traits are now seen by the
`collect_intra_doc_links` pass. There are also some minor changes in
librustdoc/fold.rs to avoid borrowing the extern_traits RefCell more
than once at a time.
|
|
This removes the incorrect error, but doesn't show the documentation
anywhere.
|
|
Unify error reporting for intra-doc links
- Give a suggestion even if there is no span available
- Give a more accurate description of the change than 'use the
disambiguator'
- Write much less code
Closes #75836.
r? @euclio
cc @pickfire - this gets rid of 'disambiguator' like you suggested in https://github.com/rust-lang/rust/pull/75079#discussion_r464464195.
|
|
This modules contains the implementation of doctests, and not the
tests of rustdoc itself. This name is confusing, so let's rename it to
doctest for clarity.
|
|
This fixes a regression introduced in
https://github.com/rust-lang/rust/pull/74855.
|
|
|
|
|
|
|
|
- Give a suggestion even if there is no span available
- Give a more accurate description of the change than 'use the
disambiguator'
- Write much less code
|
|
Add some timing info to rustdoc
There are various improvements, but the main one is to time each pass
that rustdoc performs (`rustdoc::passes`).
Before, these were the top five timings for `cargo doc` on the cargo
repository:
```
+---------------------------------+-----------+-----------------+----------+------------+
| Item | Self time | % of total time | Time | Item count |
+---------------------------------+-----------+-----------------+----------+------------+
| <unknown> | 854.70ms | 20.888 | 2.47s | 744823 |
+---------------------------------+-----------+-----------------+----------+------------+
| expand_crate | 795.29ms | 19.436 | 848.00ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| metadata_decode_entry | 256.73ms | 6.274 | 279.49ms | 518344 |
+---------------------------------+-----------+-----------------+----------+------------+
| resolve_crate | 240.56ms | 5.879 | 242.86ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| hir_lowering | 146.79ms | 3.587 | 146.79ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
```
Now the timings are:
```
+---------------------------------+-----------+-----------------+----------+------------+
| Item | Self time | % of total time | Time | Item count |
+---------------------------------+-----------+-----------------+----------+------------+
| <unknown> | 1.40s | 22.662 | 3.73s | 771430 |
+---------------------------------+-----------+-----------------+----------+------------+
| collect-trait-impls | 1.34s | 21.672 | 2.87s | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| expand_crate | 1.21s | 19.577 | 1.28s | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| build extern trait impl | 704.66ms | 11.427 | 1.07s | 21893 |
+---------------------------------+-----------+-----------------+----------+------------+
| metadata_decode_entry | 354.84ms | 5.754 | 391.81ms | 544919 |
+---------------------------------+-----------+-----------------+----------+------------+
```
The goal is to help me debug regressions like https://github.com/rust-lang/rust/pull/74518#issuecomment-661498214 (currently I have _no_ idea what could have gone wrong).
r? @eddyb or @Mark-Simulacrum
|
|
|
|
There are various improvements, but the main one is to time each pass
that rustdoc performs (`rustdoc::passes`).
Before, these were the top five timings for `cargo doc` on the cargo
repository:
```
+---------------------------------+-----------+-----------------+----------+------------+
| Item | Self time | % of total time | Time | Item count |
+---------------------------------+-----------+-----------------+----------+------------+
| <unknown> | 854.70ms | 20.888 | 2.47s | 744823 |
+---------------------------------+-----------+-----------------+----------+------------+
| expand_crate | 795.29ms | 19.436 | 848.00ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| metadata_decode_entry | 256.73ms | 6.274 | 279.49ms | 518344 |
+---------------------------------+-----------+-----------------+----------+------------+
| resolve_crate | 240.56ms | 5.879 | 242.86ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| hir_lowering | 146.79ms | 3.587 | 146.79ms | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
```
Now the timings are:
```
+---------------------------------+-----------+-----------------+----------+------------+
| Item | Self time | % of total time | Time | Item count |
+---------------------------------+-----------+-----------------+----------+------------+
| <unknown> | 1.40s | 22.662 | 3.73s | 771430 |
+---------------------------------+-----------+-----------------+----------+------------+
| collect-trait-impls | 1.34s | 21.672 | 2.87s | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| expand_crate | 1.21s | 19.577 | 1.28s | 1 |
+---------------------------------+-----------+-----------------+----------+------------+
| build extern trait impl | 704.66ms | 11.427 | 1.07s | 21893 |
+---------------------------------+-----------+-----------------+----------+------------+
| metadata_decode_entry | 354.84ms | 5.754 | 391.81ms | 544919 |
+---------------------------------+-----------+-----------------+----------+------------+
```
|
|
|
|
- Add a new `prim@` disambiguator, since both modules and primitives are
in the same namespace
- Refactor `report_ambiguity` into a closure
Additionally, I noticed that rustdoc would previously allow
`[struct@char]` if `char` resolved to a primitive (not if it had a
DefId). I fixed that and added a test case.
|
|
Fix intra-doc links for associated items
@Manishearth and I found that links of the following sort are broken:
```rust
$ cat str_from.rs
/// [`String::from`]
pub fn foo() {}
$ rustdoc str_from.rs
warning: `[String::from]` cannot be resolved, ignoring it.
--> str_from.rs:4:6
|
4 | /// [`String::from`]
| ^^^^^^^^^^^^^^ cannot be resolved, ignoring
```
It turns out this is because the current implementation only looks at inherent impls (`impl Bar {}`) and traits _for the item being documented_. Note that this is not the same as the item being _linked_ to. So this code would work:
```rust
pub trait T1 {
fn method();
}
pub struct S;
impl T1 for S {
/// [S::method] on method
fn method() {}
}
```
but putting the documentation on `trait T1` would not.
~~I realized that writing it up that my fix is only partially correct: It removes the inherent impls code when it should instead remove the `trait_item` code.~~ Fixed.
Additionally, I discovered while writing this there is some ambiguity: you could have multiple methods with the same name, but for different traits:
```rust
pub trait T1 {
fn method();
}
pub trait T2 {
fn method();
}
/// See [S::method]
pub struct S;
```
Rustdoc should give an ambiguity error here, but since there is currently no way to disambiguate the traits (https://github.com/rust-lang/rust/issues/74563) it does not (https://github.com/rust-lang/rust/pull/74489#issuecomment-673878404).
There is a _third_ ambiguity that pops up: What if the trait is generic and is implemented multiple times with different generic parameters? In this case, my fix does not do very well: it thinks there is only one trait instantiated and links to that trait:
```
/// [`String::from`] -- this resolves to https://doc.rust-lang.org/nightly/alloc/string/struct.String.html#method.from
pub fn foo() {}
```
However, every `From` implementation has a method called `from`! So the browser picks a random one. This is not the desired behavior, but it's not clear how to avoid it.
To be consistent with the rest of intra-doc links, this only resolves associated items from traits that are in scope. This required changes to rustc_resolve to work cross-crate; the relevant commits are prefixed with `resolve: `. As a bonus, considering only traits in scope is slightly faster. To avoid re-calculating the traits over and over, rustdoc uses a cache to store the traits in scope for a given module.
|
|
GuillaumeGomez:missing-doc-examples-lint-improvements, r=jyn514
Missing doc examples lint improvements
Fixes #75719.
To be merged after #75718 (only the two last commits are from this PR).
Since you already reviewed #75718, I'll set you as reviewer here as well. :)
r? @jyn514
|
|
|
|
This avoids taking the slow path several thousand times in a row.
- Fallback to all traits if the traits in scope are unknown
- Use a rustdoc thread_local cache instead of a query
The set of traits implemented by a type is not stable across crates:
there could be new traits added in a new crate.
- Use DocContext instead of a thread-local
|
|
Previously, associated items would only be available for linking
directly on the `impl Trait for Type`. Now they can be used anywhere.
- Make `item` for resolve mandatory
- Refactor resolving associated items into a separate function
- Remove broken trait_item logic
- Don't skip the type namespace for associated items
- Only call `variant_field` for `TypeNS`
- Add test for associated items
- Use exhaustive matches instead of wildcards
Wildcards caused several bugs while implementing this.
|
|
Remove duplication in `fold_item`
r? @Manishearth
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Co-authored-by: lzutao <taolzu@gmail.com>
|
|
|
|
|
