[WIP] rustdoc (base+json): add support for variances #123219

fmease · 2024-03-30T02:01:38Z

I had this patch lying around for more than a month without much progress. Submitting this now to move things forward hopefully.

Addresses part of #22108.

For the sake transparency let me mention that I've stalled work on this because I haven't had the time to find ways to obtain or represent the “reason” / “provenance” of variances — a feature kindly requested by @obi1kenobi, maintainer of cargo-semver-checks. With “reason” we're referring to the set of constituent types that have had an influence on the variance of a given generic parameter.

This information could then be used in diagnostics emitted by cargo-semver-checks à la “variance of param T of ty S changed from covariant to contravariant because you changed the type of field f from T to fn(T). On second thought though, this seems like a major add-on and I fear that it's infeasible to implement (smh. exposing the necessary info from rustc). On the other hand, this feature probably has a large impact on the design of the final API (i.e., how we represent variances in rustdoc JSON). I definitely don't want to hand-roll variance computation inside rustdoc.

TODOs:

clean up the implementation (see individual FIXMEs)
write docs for rustdoc-json-types
add rustdoc JSON tests

r? ghost

In anticipation of adding variance to them.

fmease · 2024-03-30T02:01:59Z

@bors try @rust-timer queue

[WIP] rustdoc (base+json): add support for variances I had this patch lying around for more than a month without much progress. Submitting this now to move things forward hopefully. Addresses part of rust-lang#22108. --- For transparency, I've stalled work on this because I haven't had the time to find ways to obtain or represent the “reason” / “provenance” of variances — a feature kindly requested by `@obi1kenobi,` maintainer of cargo-semver-checks. With “reason” we're referring to the set of constituent types that have had an influence on the variance of a given generic parameter. This information could then be used in the diagnostics of cargo-semver-checks à la “variance of param `T` of ty `S` changed from covariant to contravariant because you changed the type of field `f` from `T` to `fn(T)”. On second thought, this seems like a major add-on and I fear that it's infeasible to implement this (smh. exposing the necessary info from rustc). On the other hand, this feature probably has a large impact on the design of the final API (i.e., how we represent variances in rustdoc JSON). I definitely don't want to hand-roll variance computation inside rustdoc. --- TODOs: * clean up the implementation (see individual FIXMEs) * write docs for `rustdoc-json-types` * add rustdoc JSON tests r? ghost

bors · 2024-03-30T02:03:08Z

⌛ Trying commit 3781173 with merge 77b18b0...

bors · 2024-03-30T03:33:47Z

☀️ Try build successful - checks-actions
Build commit: 77b18b0 (77b18b03b397e46dcdcb31d6805f56928324c3a1)

bors · 2024-03-30T03:33:48Z

☀️ Try build successful - checks-actions
Build commit: 77b18b0 (77b18b03b397e46dcdcb31d6805f56928324c3a1)

rust-timer · 2024-03-30T05:00:42Z

Finished benchmarking commit (77b18b0): comparison URL.

Overall result: ❌ regressions - ACTION NEEDED

Benchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf.

Next Steps: If you can justify the regressions found in this try perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please fix the regressions and do another perf run. If the next run shows neutral or positive results, the label will be automatically removed.

@bors rollup=never
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	0.3%	[0.2%, 0.5%]	8
Regressions ❌ (secondary)	0.7%	[0.3%, 2.2%]	11
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	0.3%	[0.2%, 0.5%]	8

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	3.9%	[3.9%, 3.9%]	1
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-1.8%	[-1.8%, -1.8%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	1.1%	[-1.8%, 3.9%]	2

Cycles

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-1.0%	[-1.1%, -1.0%]	2
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-1.0%	[-1.1%, -1.0%]	2

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 668.236s -> 667.965s (-0.04%)
Artifact size: 315.84 MiB -> 315.88 MiB (0.01%)

rust-log-analyzer · 2024-04-02T02:02:30Z

The job x86_64-gnu-llvm-17 failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

#17 exporting to docker image format
#17 sending tarball 31.6s done
#17 DONE 36.9s
##[endgroup]
Setting extra environment values for docker:  --env ENABLE_GCC_CODEGEN=1 --env GCC_EXEC_PREFIX=/usr/lib/gcc/
[CI_JOB_NAME=x86_64-gnu-llvm-17]
---
sccache: Starting the server...
##[group]Configure the build
configure: processing command line
configure: 
configure: build.configure-args := ['--build=x86_64-unknown-linux-gnu', '--llvm-root=/usr/lib/llvm-17', '--enable-llvm-link-shared', '--set', 'rust.thin-lto-import-instr-limit=10', '--set', 'change-id=99999999', '--enable-verbose-configure', '--enable-sccache', '--disable-manage-submodules', '--enable-locked-deps', '--enable-cargo-native-static', '--set', 'rust.codegen-units-std=1', '--set', 'dist.compression-profile=balanced', '--dist-compression-formats=xz', '--disable-dist-src', '--release-channel=nightly', '--enable-debug-assertions', '--enable-overflow-checks', '--enable-llvm-assertions', '--set', 'rust.verify-llvm-ir', '--set', 'rust.codegen-backends=llvm,cranelift,gcc', '--set', 'llvm.static-libstdcpp', '--enable-new-symbol-mangling']
configure: target.x86_64-unknown-linux-gnu.llvm-config := /usr/lib/llvm-17/bin/llvm-config
configure: llvm.link-shared     := True
configure: rust.thin-lto-import-instr-limit := 10
configure: change-id            := 99999999
---
  Downloaded boml v0.3.1
   Compiling boml v0.3.1
   Compiling y v0.1.0 (/checkout/compiler/rustc_codegen_gcc/build_system)
    Finished `release` profile [optimized] target(s) in 3.33s
     Running `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-codegen/x86_64-unknown-linux-gnu/release/y test --use-system-gcc --use-backend gcc --out-dir /checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools/cg_gcc --release --mini-tests --std-tests`
Using system GCC
[BUILD] example
[AOT] mini_core_hello_world
/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools/cg_gcc/mini_core_hello_world
abc
---
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fn_pointer/generics" "--template" "/checkout/tests/rustdoc-json/fn_pointer/generics.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='WithHigherRankTraitBounds')].inner.type_alias.type.function_pointer.generic_params[0].kind matched to [Object {"lifetime": Object {"variance": Null, "outlives": Array []}}], but expected Object {"lifetime": Object {"outlives": Array []}} on line 9
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/fn_pointer/generics.rs"
------------------------------------------

Rustdoc Output:
Rustdoc Output:
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fn_pointer/generics/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fn_pointer/generics" "--deny" "warnings" "/checkout/tests/rustdoc-json/fn_pointer/generics.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none


---- [rustdoc-json] tests/rustdoc-json/fns/generic_args.rs stdout ----
---- [rustdoc-json] tests/rustdoc-json/fns/generic_args.rs stdout ----

error: jsondocck failed!
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fns/generic_args" "--template" "/checkout/tests/rustdoc-json/fns/generic_args.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='where_clase')].inner.function.generics.params[0].kind matched to [Object {"type": Object {"variance": String("contravariant"), "bounds": Array [], "default": Null, "synthetic": Bool(false)}}], but expected Object {"type": Object {"bounds": Array [], "default": Null, "synthetic": Bool(false)}} on line 32
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/fns/generic_args.rs"

Rustdoc Output:
status: exit status: 0
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fns/generic_args/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/fns/generic_args" "--deny" "warnings" "/checkout/tests/rustdoc-json/fns/generic_args.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none


---- [rustdoc-json] tests/rustdoc-json/lifetime/longest.rs stdout ----
---- [rustdoc-json] tests/rustdoc-json/lifetime/longest.rs stdout ----

error: jsondocck failed!
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/lifetime/longest" "--template" "/checkout/tests/rustdoc-json/lifetime/longest.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='longest')].inner.function.generics.params[0].kind matched to [Object {"lifetime": Object {"variance": Null, "outlives": Array []}}], but expected Object {"lifetime": Object {"outlives": Array []}} on line 4
Failed check: $.index[*][?(@.name=='longest')].inner.function.generics.params[0].kind matched to [Object {"lifetime": Object {"variance": Null, "outlives": Array []}}], but expected Object {"lifetime": Object {"outlives": Array []}} on line 5
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/lifetime/longest.rs"

Rustdoc Output:
status: exit status: 0
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/lifetime/longest/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/lifetime/longest" "--deny" "warnings" "/checkout/tests/rustdoc-json/lifetime/longest.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none


---- [rustdoc-json] tests/rustdoc-json/non_lifetime_binders.rs stdout ----
---- [rustdoc-json] tests/rustdoc-json/non_lifetime_binders.rs stdout ----

error: jsondocck failed!
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/non_lifetime_binders" "--template" "/checkout/tests/rustdoc-json/non_lifetime_binders.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='foo')].inner.function.generics.where_predicates[0].bound_predicate.generic_params[0].kind matched to [Object {"lifetime": Object {"variance": Null, "outlives": Array []}}], but expected Object {"lifetime": Object {"outlives": Array []}} on line 12
Failed check: $.index[*][?(@.name=='foo')].inner.function.generics.where_predicates[0].bound_predicate.generic_params[1].kind matched to [Object {"type": Object {"variance": Null, "bounds": Array [], "default": Null, "synthetic": Bool(false)}}], but expected Object {"type": Object {"bounds": Array [], "default": Null, "synthetic": Bool(false)}} on line 14
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/non_lifetime_binders.rs"

Rustdoc Output:
status: exit status: 0
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/non_lifetime_binders/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/non_lifetime_binders" "--deny" "warnings" "/checkout/tests/rustdoc-json/non_lifetime_binders.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none


---- [rustdoc-json] tests/rustdoc-json/type/dyn.rs stdout ----
---- [rustdoc-json] tests/rustdoc-json/type/dyn.rs stdout ----

error: jsondocck failed!
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/dyn" "--template" "/checkout/tests/rustdoc-json/type/dyn.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='RefFn')].inner.type_alias.generics matched to [Object {"params": Array [Object {"name": String("'a"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}], "where_predicates": Array []}], but expected Object {"params": Array [Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'a")}], "where_predicates": Array []} on line 29
Failed check: $.index[*][?(@.name=='RefFn')].inner.type_alias.type.borrowed_ref.type.dyn_trait.traits[0].generic_params matched to [Array [Object {"name": String("'b"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}]], but expected Array [Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'b")}] on line 36
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/type/dyn.rs"

Rustdoc Output:
status: exit status: 0
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/dyn/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/dyn" "--deny" "warnings" "/checkout/tests/rustdoc-json/type/dyn.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none


---- [rustdoc-json] tests/rustdoc-json/type/hrtb.rs stdout ----
---- [rustdoc-json] tests/rustdoc-json/type/hrtb.rs stdout ----

error: jsondocck failed!
status: exit status: 1
command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/jsondocck" "--doc-dir" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/hrtb" "--template" "/checkout/tests/rustdoc-json/type/hrtb.rs"
stdout: none
--- stderr -------------------------------
Failed check: $.index[*][?(@.name=='genfn')].inner.function.generics.where_predicates[0].bound_predicate.generic_params matched to [Array [Object {"name": String("'a"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}, Object {"name": String("'b"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}]], but expected Array [Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'a")}, Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'b")}] on line 4
Failed check: $.index[*][?(@.name=='dynfn')].inner.function.decl.inputs[0][1].borrowed_ref.type.dyn_trait.traits[0].generic_params matched to [Array [Object {"name": String("'a"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}, Object {"name": String("'b"), "kind": Object {"lifetime": Object {"variance": Null, "outlives": Array []}}}]], but expected Array [Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'a")}, Object {"kind": Object {"lifetime": Object {"outlives": Array []}}, "name": String("'b")}] on line 17
Error: "Jsondocck failed for /checkout/tests/rustdoc-json/type/hrtb.rs"

Rustdoc Output:
status: exit status: 0
status: exit status: 0
command: RUSTC_ICE="0" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/hrtb/auxiliary" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-json/type/hrtb" "--deny" "warnings" "/checkout/tests/rustdoc-json/type/hrtb.rs" "-A" "internal_features" "--output-format" "json" "-Zunstable-options"
stderr: none

bors · 2024-04-02T15:03:48Z

☔ The latest upstream changes (presumably #123340) made this pull request unmergeable. Please resolve the merge conflicts.

Dylan-DPC · 2024-08-12T11:38:02Z

@fmease any updates on this? thanks

fmease added 3 commits March 30, 2024 02:12

rustdoc: pass owner item of generics to cleaning functions

bdc8c5c

rustdoc: change memory repr of generic params

23f9e1a

In anticipation of adding variance to them.

rustdoc: clean: add support for variances

7406e00

rustbot added A-rustdoc-json Area: Rustdoc JSON backend S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Mar 30, 2024

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Mar 30, 2024

fmease added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 30, 2024

fmease mentioned this pull request Mar 30, 2024

[blocked on design] [PoC]: rustdoc (html): add support for variances #123220

Draft

This comment has been minimized.

Sign in to view

rustbot added perf-regression Performance regression. and removed S-waiting-on-perf Status: Waiting on a perf run to be completed. labels Mar 30, 2024

rustdoc: json: add support for variances

e381cb4

fmease force-pushed the rustdoc-variances-json branch from 3781173 to e381cb4 Compare April 2, 2024 01:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] rustdoc (base+json): add support for variances #123219

[WIP] rustdoc (base+json): add support for variances #123219

fmease commented Mar 30, 2024 •

edited

Loading

fmease commented Mar 30, 2024

This comment has been minimized.

bors commented Mar 30, 2024

This comment has been minimized.

bors commented Mar 30, 2024

bors commented Mar 30, 2024

This comment has been minimized.

rust-timer commented Mar 30, 2024

rust-log-analyzer commented Apr 2, 2024

bors commented Apr 2, 2024

Dylan-DPC commented Aug 12, 2024

[WIP] rustdoc (base+json): add support for variances #123219

Are you sure you want to change the base?

[WIP] rustdoc (base+json): add support for variances #123219

Conversation

fmease commented Mar 30, 2024 • edited Loading

fmease commented Mar 30, 2024

This comment has been minimized.

bors commented Mar 30, 2024

This comment has been minimized.

bors commented Mar 30, 2024

bors commented Mar 30, 2024

This comment has been minimized.

rust-timer commented Mar 30, 2024

Overall result: ❌ regressions - ACTION NEEDED

Instruction count

Max RSS (memory usage)

Cycles

Binary size

rust-log-analyzer commented Apr 2, 2024

bors commented Apr 2, 2024

Dylan-DPC commented Aug 12, 2024

fmease commented Mar 30, 2024 •

edited

Loading