Skip to content

Commit 6f349cd

Browse files
borsbors
committed
Auto merge of #116471 - notriddle:notriddle/js-trait-alias, r=GuillaumeGomez
rustdoc: use JS to inline target type impl docs into alias Preview docs: - https://notriddle.com/rustdoc-html-demo-5/js-trait-alias/std/io/type.Result.html - https://notriddle.com/rustdoc-html-demo-5/js-trait-alias-compiler/rustc_middle/ty/type.PolyTraitRef.html This pull request also includes a bug fix for trait alias inlining across crates. This means more documentation is generated, and is why ripgrep runs slower (it's a thin wrapper on top of the `grep` crate, so 5% of its docs are now the Result type). - Before, built with rustdoc 1.75.0-nightly (aa1a71e 2023-10-26), Result type alias method docs are missing: http://notriddle.com/rustdoc-html-demo-5/ripgrep-js-nightly/rg/type.Result.html - After, built with this branch, all the methods on Result are shown: http://notriddle.com/rustdoc-html-demo-5/ripgrep-js-trait-alias/rg/type.Result.html *Review note: This is mostly just reverting #115201. The last commit has the new work in it.* Fixes #115718 This is an attempt to balance three problems, each of which would be violated by a simpler implementation: - A type alias should show all the `impl` blocks for the target type, and vice versa, if they're applicable. If nothing was done, and rustdoc continues to match them up in HIR, this would not work. - Copying the target type's docs into its aliases' HTML pages directly causes far too much redundant HTML text to be generated when a crate has large numbers of methods and large numbers of type aliases. - Using JavaScript exclusively for type alias impl docs would be a functional regression, and could make some docs very hard to find for non-JS readers. - Making sure that only applicable docs are show in the resulting page requires a type checkers. Do not reimplement the type checker in JavaScript. So, to make it work, rustdoc stashes these type-alias-inlined docs in a JSONP "database-lite". The file is generated in `write_shared.rs`, included in a `<script>` tag added in `print_item.rs`, and `main.js` takes care of patching the additional docs into the DOM. The format of `trait.impl` and `type.impl` JS files are superficially similar. Each line, except the JSONP wrapper itself, belongs to a crate, and they are otherwise separate (rustdoc should be idempotent). The "meat" of the file is HTML strings, so the frontend code is very simple. Links are relative to the doc root, though, so the frontend needs to fix that up, and inlined docs can reuse these files. However, there are a few differences, caused by the sophisticated features that type aliases have. Consider this crate graph: ```text --------------------------------- | crate A: struct Foo<T> | | type Bar = Foo<i32> | | impl X for Foo<i8> | | impl Y for Foo<i32> | --------------------------------- | ---------------------------------- | crate B: type Baz = A::Foo<i8> | | type Xyy = A::Foo<i8> | | impl Z for Xyy | ---------------------------------- ``` The type.impl/A/struct.Foo.js JS file has a structure kinda like this: ```js JSONP({ "A": [["impl Y for Foo<i32>", "Y", "A::Bar"]], "B": [["impl X for Foo<i8>", "X", "B::Baz", "B::Xyy"], ["impl Z for Xyy", "Z", "B::Baz"]], }); ``` When the type.impl file is loaded, only the current crate's docs are actually used. The main reason to bundle them together is that there's enough duplication in them for DEFLATE to remove the redundancy. The contents of a crate are a list of impl blocks, themselves represented as lists. The first item in the sublist is the HTML block, the second item is the name of the trait (which goes in the sidebar), and all others are the names of type aliases that successfully match. This way: - There's no need to generate these files for types that have no aliases in the current crate. If a dependent crate makes a type alias, it'll take care of generating its own docs. - There's no need to reimplement parts of the type checker in JavaScript. The Rust backend does the checking, and includes its results in the file. - Docs defined directly on the type alias are dropped directly in the HTML by `render_assoc_items`, and are accessible without JavaScript. The JSONP file will not list impl items that are known to be part of the main HTML file already. [JSONP]: https://en.wikipedia.org/wiki/JSONP
2 parents 2f1bd07 + 46fdeb2 commit 6f349cd

36 files changed

+920
-151
lines changed

‎Cargo.lock

+1
Original file line numberDiff line numberDiff line change
@@ -4692,6 +4692,7 @@ dependencies = [
46924692
"arrayvec",
46934693
"askama",
46944694
"expect-test",
4695+
"indexmap 2.0.0",
46954696
"itertools",
46964697
"minifier",
46974698
"once_cell",

‎src/librustdoc/Cargo.toml

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ path = "lib.rs"
1010
arrayvec = { version = "0.7", default-features = false }
1111
askama = { version = "0.12", default-features = false, features = ["config"] }
1212
itertools = "0.10.1"
13+
indexmap = "2"
1314
minifier = "0.2.3"
1415
once_cell = "1.10.0"
1516
regex = "1"

‎src/librustdoc/clean/inline.rs

+9-3
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ use crate::clean::{
2626
use crate::core::DocContext;
2727
use crate::formats::item_type::ItemType;
2828

29+
use super::Item;
30+
2931
/// Attempt to inline a definition into this AST.
3032
///
3133
/// This function will fetch the definition specified, and if it is
@@ -83,7 +85,7 @@ pub(crate) fn try_inline(
8385
Res::Def(DefKind::TyAlias, did) => {
8486
record_extern_fqn(cx, did, ItemType::TypeAlias);
8587
build_impls(cx, did, attrs_without_docs, &mut ret);
86-
clean::TypeAliasItem(build_type_alias(cx, did))
88+
clean::TypeAliasItem(build_type_alias(cx, did, &mut ret))
8789
}
8890
Res::Def(DefKind::Enum, did) => {
8991
record_extern_fqn(cx, did, ItemType::Enum);
@@ -281,11 +283,15 @@ fn build_union(cx: &mut DocContext<'_>, did: DefId) -> clean::Union {
281283
clean::Union { generics, fields }
282284
}
283285

284-
fn build_type_alias(cx: &mut DocContext<'_>, did: DefId) -> Box<clean::TypeAlias> {
286+
fn build_type_alias(
287+
cx: &mut DocContext<'_>,
288+
did: DefId,
289+
ret: &mut Vec<Item>,
290+
) -> Box<clean::TypeAlias> {
285291
let predicates = cx.tcx.explicit_predicates_of(did);
286292
let ty = cx.tcx.type_of(did).instantiate_identity();
287293
let type_ = clean_middle_ty(ty::Binder::dummy(ty), cx, Some(did), None);
288-
let inner_type = clean_ty_alias_inner_type(ty, cx);
294+
let inner_type = clean_ty_alias_inner_type(ty, cx, ret);
289295

290296
Box::new(clean::TypeAlias {
291297
type_,

‎src/librustdoc/clean/mod.rs

+32-7
Original file line numberDiff line numberDiff line change
@@ -934,18 +934,27 @@ fn clean_ty_generics<'tcx>(
934934
fn clean_ty_alias_inner_type<'tcx>(
935935
ty: Ty<'tcx>,
936936
cx: &mut DocContext<'tcx>,
937+
ret: &mut Vec<Item>,
937938
) -> Option<TypeAliasInnerType> {
938939
let ty::Adt(adt_def, args) = ty.kind() else {
939940
return None;
940941
};
941942

943+
if !adt_def.did().is_local() {
944+
inline::build_impls(cx, adt_def.did(), None, ret);
945+
}
946+
942947
Some(if adt_def.is_enum() {
943948
let variants: rustc_index::IndexVec<_, _> = adt_def
944949
.variants()
945950
.iter()
946951
.map(|variant| clean_variant_def_with_args(variant, args, cx))
947952
.collect();
948953

954+
if !adt_def.did().is_local() {
955+
inline::record_extern_fqn(cx, adt_def.did(), ItemType::Enum);
956+
}
957+
949958
TypeAliasInnerType::Enum {
950959
variants,
951960
is_non_exhaustive: adt_def.is_variant_list_non_exhaustive(),
@@ -961,8 +970,14 @@ fn clean_ty_alias_inner_type<'tcx>(
961970
clean_variant_def_with_args(variant, args, cx).kind.inner_items().cloned().collect();
962971

963972
if adt_def.is_struct() {
973+
if !adt_def.did().is_local() {
974+
inline::record_extern_fqn(cx, adt_def.did(), ItemType::Struct);
975+
}
964976
TypeAliasInnerType::Struct { ctor_kind: variant.ctor_kind(), fields }
965977
} else {
978+
if !adt_def.did().is_local() {
979+
inline::record_extern_fqn(cx, adt_def.did(), ItemType::Union);
980+
}
966981
TypeAliasInnerType::Union { fields }
967982
}
968983
})
@@ -2744,14 +2759,24 @@ fn clean_maybe_renamed_item<'tcx>(
27442759
}
27452760

27462761
let ty = cx.tcx.type_of(def_id).instantiate_identity();
2747-
let inner_type = clean_ty_alias_inner_type(ty, cx);
27482762

2749-
TypeAliasItem(Box::new(TypeAlias {
2750-
generics,
2751-
inner_type,
2752-
type_: rustdoc_ty,
2753-
item_type: Some(type_),
2754-
}))
2763+
let mut ret = Vec::new();
2764+
let inner_type = clean_ty_alias_inner_type(ty, cx, &mut ret);
2765+
2766+
ret.push(generate_item_with_correct_attrs(
2767+
cx,
2768+
TypeAliasItem(Box::new(TypeAlias {
2769+
generics,
2770+
inner_type,
2771+
type_: rustdoc_ty,
2772+
item_type: Some(type_),
2773+
})),
2774+
item.owner_id.def_id.to_def_id(),
2775+
name,
2776+
import_id,
2777+
renamed,
2778+
));
2779+
return ret;
27552780
}
27562781
ItemKind::Enum(ref def, generics) => EnumItem(Enum {
27572782
variants: def.variants.iter().map(|v| clean_variant(v, cx)).collect(),

‎src/librustdoc/formats/cache.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ pub(crate) struct Cache {
5050
/// Unlike 'paths', this mapping ignores any renames that occur
5151
/// due to 'use' statements.
5252
///
53-
/// This map is used when writing out the special 'implementors'
54-
/// javascript file. By using the exact path that the type
53+
/// This map is used when writing out the `impl.trait` and `impl.type`
54+
/// javascript files. By using the exact path that the type
5555
/// is declared with, we ensure that each path will be identical
5656
/// to the path used if the corresponding type is inlined. By
5757
/// doing this, we can detect duplicate impls on a trait page, and only display

‎src/librustdoc/formats/item_type.rs

+3
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,9 @@ impl ItemType {
180180
pub(crate) fn is_method(&self) -> bool {
181181
matches!(*self, ItemType::Method | ItemType::TyMethod)
182182
}
183+
pub(crate) fn is_adt(&self) -> bool {
184+
matches!(*self, ItemType::Struct | ItemType::Union | ItemType::Enum)
185+
}
183186
}
184187

185188
impl fmt::Display for ItemType {

‎src/librustdoc/html/render/context.rs

+2-51
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,8 @@ use std::sync::mpsc::{channel, Receiver};
77

88
use rustc_data_structures::fx::{FxHashMap, FxHashSet};
99
use rustc_hir::def_id::{DefIdMap, LOCAL_CRATE};
10-
use rustc_middle::ty::fast_reject::{DeepRejectCtxt, TreatParams};
1110
use rustc_middle::ty::TyCtxt;
1211
use rustc_session::Session;
13-
use rustc_span::def_id::DefId;
1412
use rustc_span::edition::Edition;
1513
use rustc_span::source_map::FileName;
1614
use rustc_span::{sym, Symbol};
@@ -25,13 +23,13 @@ use super::{
2523
AllTypes, LinkFromSrc, StylePath,
2624
};
2725
use crate::clean::utils::has_doc_flag;
28-
use crate::clean::{self, types::ExternalLocation, ExternalCrate, TypeAliasItem};
26+
use crate::clean::{self, types::ExternalLocation, ExternalCrate};
2927
use crate::config::{ModuleSorting, RenderOptions};
3028
use crate::docfs::{DocFS, PathError};
3129
use crate::error::Error;
3230
use crate::formats::cache::Cache;
3331
use crate::formats::item_type::ItemType;
34-
use crate::formats::{self, FormatRenderer};
32+
use crate::formats::FormatRenderer;
3533
use crate::html::escape::Escape;
3634
use crate::html::format::{join_with_double_colon, Buffer};
3735
use crate::html::markdown::{self, plain_text_summary, ErrorCodes, IdMap};
@@ -150,53 +148,6 @@ impl SharedContext<'_> {
150148
pub(crate) fn edition(&self) -> Edition {
151149
self.tcx.sess.edition()
152150
}
153-
154-
/// Returns a list of impls on the given type, and, if it's a type alias,
155-
/// other types that it aliases.
156-
pub(crate) fn all_impls_for_item<'a>(
157-
&'a self,
158-
it: &clean::Item,
159-
did: DefId,
160-
) -> Vec<&'a formats::Impl> {
161-
let tcx = self.tcx;
162-
let cache = &self.cache;
163-
let mut saw_impls = FxHashSet::default();
164-
let mut v: Vec<&formats::Impl> = cache
165-
.impls
166-
.get(&did)
167-
.map(Vec::as_slice)
168-
.unwrap_or(&[])
169-
.iter()
170-
.filter(|i| saw_impls.insert(i.def_id()))
171-
.collect();
172-
if let TypeAliasItem(ait) = &*it.kind &&
173-
let aliased_clean_type = ait.item_type.as_ref().unwrap_or(&ait.type_) &&
174-
let Some(aliased_type_defid) = aliased_clean_type.def_id(cache) &&
175-
let Some(av) = cache.impls.get(&aliased_type_defid) &&
176-
let Some(alias_def_id) = it.item_id.as_def_id()
177-
{
178-
// This branch of the compiler compares types structually, but does
179-
// not check trait bounds. That's probably fine, since type aliases
180-
// don't normally constrain on them anyway.
181-
// https://github.com/rust-lang/rust/issues/21903
182-
//
183-
// FIXME(lazy_type_alias): Once the feature is complete or stable, rewrite this to use type unification.
184-
// Be aware of `tests/rustdoc/issue-112515-impl-ty-alias.rs` which might regress.
185-
let aliased_ty = tcx.type_of(alias_def_id).skip_binder();
186-
let reject_cx = DeepRejectCtxt {
187-
treat_obligation_params: TreatParams::AsCandidateKey,
188-
};
189-
v.extend(av.iter().filter(|impl_| {
190-
if let Some(impl_def_id) = impl_.impl_item.item_id.as_def_id() {
191-
reject_cx.types_may_unify(aliased_ty, tcx.type_of(impl_def_id).skip_binder())
192-
&& saw_impls.insert(impl_def_id)
193-
} else {
194-
false
195-
}
196-
}));
197-
}
198-
v
199-
}
200151
}
201152

202153
impl<'tcx> Context<'tcx> {

‎src/librustdoc/html/render/mod.rs

+9-16
Original file line numberDiff line numberDiff line change
@@ -1145,13 +1145,13 @@ pub(crate) fn render_all_impls(
11451145
fn render_assoc_items<'a, 'cx: 'a>(
11461146
cx: &'a mut Context<'cx>,
11471147
containing_item: &'a clean::Item,
1148-
did: DefId,
1148+
it: DefId,
11491149
what: AssocItemRender<'a>,
11501150
) -> impl fmt::Display + 'a + Captures<'cx> {
11511151
let mut derefs = DefIdSet::default();
1152-
derefs.insert(did);
1152+
derefs.insert(it);
11531153
display_fn(move |f| {
1154-
render_assoc_items_inner(f, cx, containing_item, did, what, &mut derefs);
1154+
render_assoc_items_inner(f, cx, containing_item, it, what, &mut derefs);
11551155
Ok(())
11561156
})
11571157
}
@@ -1160,17 +1160,15 @@ fn render_assoc_items_inner(
11601160
mut w: &mut dyn fmt::Write,
11611161
cx: &mut Context<'_>,
11621162
containing_item: &clean::Item,
1163-
did: DefId,
1163+
it: DefId,
11641164
what: AssocItemRender<'_>,
11651165
derefs: &mut DefIdSet,
11661166
) {
11671167
info!("Documenting associated items of {:?}", containing_item.name);
11681168
let shared = Rc::clone(&cx.shared);
1169-
let v = shared.all_impls_for_item(containing_item, did);
1170-
let v = v.as_slice();
1171-
let (non_trait, traits): (Vec<&Impl>, _) =
1172-
v.iter().partition(|i| i.inner_impl().trait_.is_none());
1173-
let mut saw_impls = FxHashSet::default();
1169+
let cache = &shared.cache;
1170+
let Some(v) = cache.impls.get(&it) else { return };
1171+
let (non_trait, traits): (Vec<_>, _) = v.iter().partition(|i| i.inner_impl().trait_.is_none());
11741172
if !non_trait.is_empty() {
11751173
let mut tmp_buf = Buffer::html();
11761174
let (render_mode, id, class_html) = match what {
@@ -1199,9 +1197,6 @@ fn render_assoc_items_inner(
11991197
};
12001198
let mut impls_buf = Buffer::html();
12011199
for i in &non_trait {
1202-
if !saw_impls.insert(i.def_id()) {
1203-
continue;
1204-
}
12051200
render_impl(
12061201
&mut impls_buf,
12071202
cx,
@@ -1247,10 +1242,8 @@ fn render_assoc_items_inner(
12471242

12481243
let (synthetic, concrete): (Vec<&Impl>, Vec<&Impl>) =
12491244
traits.into_iter().partition(|t| t.inner_impl().kind.is_auto());
1250-
let (blanket_impl, concrete): (Vec<&Impl>, _) = concrete
1251-
.into_iter()
1252-
.filter(|t| saw_impls.insert(t.def_id()))
1253-
.partition(|t| t.inner_impl().kind.is_blanket());
1245+
let (blanket_impl, concrete): (Vec<&Impl>, _) =
1246+
concrete.into_iter().partition(|t| t.inner_impl().kind.is_blanket());
12541247

12551248
render_all_impls(w, cx, containing_item, &concrete, &synthetic, &blanket_impl);
12561249
}

0 commit comments

Comments
 (0)