Skip to content

Commit e0fb0dc

Browse files
Improve documentation for intra-doc links computation
1 parent d540e72 commit e0fb0dc

File tree

1 file changed

+9
-7
lines changed

1 file changed

+9
-7
lines changed

src/librustdoc/passes/collect_intra_doc_links.rs

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -288,14 +288,16 @@ pub(crate) struct LinkCollector<'a, 'tcx> {
288288
/// Cache the resolved links so we can avoid resolving (and emitting errors for) the same link.
289289
/// The link will be `None` if it could not be resolved (i.e. the error was cached).
290290
pub(crate) visited_links: FxHashMap<ResolutionInfo, Option<(Res, Option<UrlFragment>)>>,
291-
/// These links are ambiguous. We need for the cache to have its paths filled. Unfortunately,
292-
/// if we run the `LinkCollector` pass after `Cache::populate`, a lot of items that we need
293-
/// to go through will be removed, making a lot of intra-doc links to not be inferred.
291+
/// According to `rustc_resolve`, these links are ambiguous.
294292
///
295-
/// So instead, we store the ambiguous links and we wait for cache paths to be filled before
296-
/// inferring them (if possible).
293+
/// However, we cannot link to an item that has been stripped from the documentation. If all
294+
/// but one of the "possibilities" are stripped, then there is no real ambiguity. To determine
295+
/// if an ambiguity is real, we delay resolving them until after `Cache::populate`, then filter
296+
/// every item that doesn't have a cached path.
297297
///
298-
/// Key is `(item ID, path str)`.
298+
/// We could get correct results by simply delaying everything. This would have fewer happy
299+
/// codepaths, but we want to distinguish different kinds of error conditions, and this is easy
300+
/// to do by resolving links as soon as possible.
299301
pub(crate) ambiguous_links: FxIndexMap<(ItemId, String), Vec<AmbiguousLinks>>,
300302
}
301303

@@ -1188,7 +1190,7 @@ impl LinkCollector<'_, '_> {
11881190
self.cx.tcx,
11891191
BROKEN_INTRA_DOC_LINKS,
11901192
format!(
1191-
"all items matching `{path_str}` are either private or doc(hidden)"
1193+
"all items matching `{path_str}` are private or doc(hidden)"
11921194
),
11931195
&diag_info,
11941196
|diag, sp, _| {

0 commit comments

Comments
 (0)