Reword trait-object compatibility in rustdoc #126554

kornelski · 2024-06-16T16:02:12Z

"Object Safety" is a difficult to understand jargon. I'm proposing a wording that makes it clearer it's about trait objects, and mentions dyn Trait which is the syntax that users are going to be more familiar with.

Related PR: rust-lang/reference#1512

Longer explanation: https://internals.rust-lang.org/t/object-safety-is-a-terrible-term/21025

rustbot · 2024-06-16T16:02:21Z

r? @fmease

rustbot has assigned @fmease.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

fmease

Thanks for your initiative! I do agree with all of the points raised.

However, I'd like to see some official T-lang-blessed proposal. Basically what Josh has proposed here: https://internals.rust-lang.org/t/object-safety-is-a-terrible-term/21025/13 to ensure that we update the terminology everywhere consistently and "all at once" (docs, diagnostics, rustdoc, …).

Edit: I think Josh suggested to open a proposal over at https://github.com/rust-lang/lang-team.

bors · 2024-06-24T13:43:29Z

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

traviscross · 2024-09-25T07:00:56Z

@rustbot labels -I-lang-nominated

When this ongoing FCP completes, we will have decided to call traits that are compatible with dyn "dyn compatible" rather than "object safe".

fmease

The new nomenclature is "dyn-compatible", "dyn-compatibility". PR needs adjusting. See also rust-lang/lang-team#286

fmease · 2024-10-03T00:21:02Z

src/librustdoc/html/render/print_item.rs

@@ -954,13 +954,13 @@ fn item_trait(w: &mut Buffer, cx: &mut Context<'_>, it: &clean::Item, t: &clean:
    if !t.is_object_safe(cx.tcx()) {
        write_section_heading(
            w,
-            "Object Safety",
+            "Trait-Object Safety",
            "object-safety",


Suggested change

"object-safety",

"dyn-compatibility"

might need to update other references of this ID

As a nit, one would probably say that "a trait is dyn compatible" (but one might "have a dyn-compatible trait"), in the same way that we're more likely to hyphenate "a forward-compatible change" than "a change that is forward compatible".

Similarly, I'd probably say "dyn compatibility" unhyphenated, in the same way "forward compatibility" most often is.

Yeah, that makes sense (attributive vs. predicative usage). I went for unconditional hyphenation here and in my other "object safe → dyn compatible" PRs for legibility (well, that's slightly subjective I guess).

Apart from personal preference, my argument goes as follows: If you skim source code comments and documentation, a "stray" dyn has a good chance of tripping up your brain (well, that's my assumption) especially since it's jargon, not everyday language and since brains are prone to overlooking small words.

Anyway, I'm fine with conditional hyphenation here as you've suggested (since it probably looks better in the rendered HTML and my "source code skimming" argument doesn't really apply).

Tho note that this specific string should stay hyphenated for unrelated reasons – it represents the element ID.

fmease · 2024-10-03T00:21:18Z

src/librustdoc/html/render/print_item.rs

@@ -954,13 +954,13 @@ fn item_trait(w: &mut Buffer, cx: &mut Context<'_>, it: &clean::Item, t: &clean:
    if !t.is_object_safe(cx.tcx()) {
        write_section_heading(
            w,
-            "Object Safety",
+            "Trait-Object Safety",


Suggested change

"Trait-Object Safety",

"Dyn-Compatibility",

Suggested change

"Trait-Object Safety",

"Dyn Compatibility",

fmease · 2024-10-03T00:23:18Z

src/librustdoc/html/render/print_item.rs

            "object-safety",
            None,
            &format!(
-                "<div class=\"object-safety-info\">This trait is <b>not</b> \
+                "<div class=\"object-safety-info\">This trait is <strong>not</strong> compatible with \


Suggested change

"<div class=\"object-safety-info\">This trait is <strong>not</strong> compatible with \

"<div class=\"dyn-compat-info\">This trait is <strong>not</strong> compatible with \

and updating its references

fmease · 2024-10-03T00:29:26Z

src/librustdoc/html/render/print_item.rs

            "object-safety",
            None,
            &format!(
-                "<div class=\"object-safety-info\">This trait is <b>not</b> \
+                "<div class=\"object-safety-info\">This trait is <strong>not</strong> compatible with \
                <a href=\"{base}/reference/items/traits.html#object-safety\">\


You should leave a FIXME(dyn_compat_renaming): Update the URL fragment once the changes in <https://github.com/rust-lang/reference/pull/1512> reach stable.

fmease · 2024-10-03T00:31:04Z

src/librustdoc/html/render/print_item.rs

                <a href=\"{base}/reference/items/traits.html#object-safety\">\
-                object safe</a>.</div>",
+                <code>dyn Trait</code> types</a>.</div>",


Right, I guess "dyn Trait types" is fine and easy to understand. The official term is "trait object types" but that might be too jargon-y, it's hard to tell for me ^^' I use the latter all the time.

fmease · 2024-10-12T12:47:15Z

@kornelski I've opened a "competing" PR, namely #131594, which is in line with T-lang's latest resolution and a bit more comprehensive. I hope that's not too brash ^^'. Thing is, I'm having a good run updating various places that need updating and I want to land the renaming "simultaneously" (well, within the same release and ignoring the URL staging issue).

…pat, r=notriddle rustdoc: Rename "object safe" to "dyn compatible" Supersedes rust-lang#126554: 1. In line with [T-lang's latest resolution](rust-lang/lang-team#286 (comment)). 2. More comprehensive: Not only updates user-facing text but also source code. Part of rust-lang#130852. Doesn't update rustdoc-JSON (will be filed separately). r? `@notriddle` (rust-lang/lang-team#286) `@GuillaumeGomez` (for visibility)

Rollup merge of rust-lang#131594 - fmease:rustdoc-mv-obj-safe-dyn-compat, r=notriddle rustdoc: Rename "object safe" to "dyn compatible" Supersedes rust-lang#126554: 1. In line with [T-lang's latest resolution](rust-lang/lang-team#286 (comment)). 2. More comprehensive: Not only updates user-facing text but also source code. Part of rust-lang#130852. Doesn't update rustdoc-JSON (will be filed separately). r? `@notriddle` (rust-lang/lang-team#286) `@GuillaumeGomez` (for visibility)

fmease · 2024-10-16T21:06:02Z

Closing in favor of the now merged #131594. kornelski, thanks for your initial PR and for bringing up this topic in the first place!

See rust-lang#126554 (comment)

Reword trait-object compatibility in rustdoc

a1d3dbf

rustbot assigned fmease Jun 16, 2024

rustbot added 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 Jun 16, 2024

fmease added S-blocked Status: Blocked on something else such as an RFC or other implementation work. needs-fcp This change is insta-stable, so needs a completed FCP to proceed. labels Jun 18, 2024

fmease reviewed Jun 18, 2024

View reviewed changes

fmease removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 18, 2024

joshtriplett added the I-lang-nominated Nominated for discussion during a lang team meeting. label Aug 4, 2024

rustbot removed the I-lang-nominated Nominated for discussion during a lang team meeting. label Sep 25, 2024

traviscross added the T-lang Relevant to the language team, which will review and decide on the PR/issue. label Sep 25, 2024

traviscross mentioned this pull request Sep 25, 2024

Tracking issue for rename from "object safe" to "dyn compatible" #130852

Open

12 tasks

fmease added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-blocked Status: Blocked on something else such as an RFC or other implementation work. labels Sep 27, 2024

fmease requested changes Oct 3, 2024

View reviewed changes

rustbot 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 Oct 3, 2024

fmease mentioned this pull request Oct 12, 2024

rustdoc: Rename "object safe" to "dyn compatible" #131594

Merged

fmease closed this Oct 16, 2024

kornelski deleted the dyn-trait-compat-jargon branch November 18, 2024 00:35

fmease mentioned this pull request Nov 21, 2024

Add shorter and more direct error for dyn AsyncFn #133267

Open

cramertj added a commit to cramertj/rust that referenced this pull request Nov 21, 2024

Replace "dyn-compatible" with "dyn compatible"

5f7bb5f

See rust-lang#126554 (comment)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reword trait-object compatibility in rustdoc #126554

Reword trait-object compatibility in rustdoc #126554

kornelski commented Jun 16, 2024

rustbot commented Jun 16, 2024

fmease left a comment •

edited

Loading

bors commented Jun 24, 2024

traviscross commented Sep 25, 2024

fmease left a comment

fmease Oct 3, 2024

traviscross Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024

fmease Oct 3, 2024

traviscross Oct 3, 2024

fmease Oct 3, 2024

fmease Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024 •

edited

Loading

fmease commented Oct 12, 2024 •

edited

Loading

fmease commented Oct 16, 2024

	"<div class=\"object-safety-info\">This trait is <strong>not</strong> compatible with \
	"<div class=\"dyn-compat-info\">This trait is <strong>not</strong> compatible with \

Reword trait-object compatibility in rustdoc #126554

Reword trait-object compatibility in rustdoc #126554

Conversation

kornelski commented Jun 16, 2024

rustbot commented Jun 16, 2024

fmease left a comment • edited Loading

Choose a reason for hiding this comment

bors commented Jun 24, 2024

traviscross commented Sep 25, 2024

fmease left a comment

Choose a reason for hiding this comment

fmease Oct 3, 2024

Choose a reason for hiding this comment

traviscross Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

fmease Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

fmease Oct 3, 2024

Choose a reason for hiding this comment

fmease Oct 3, 2024

Choose a reason for hiding this comment

traviscross Oct 3, 2024

Choose a reason for hiding this comment

fmease Oct 3, 2024

Choose a reason for hiding this comment

fmease Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

fmease Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

fmease commented Oct 12, 2024 • edited Loading

fmease commented Oct 16, 2024

fmease left a comment •

edited

Loading

traviscross Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024 •

edited

Loading

fmease Oct 3, 2024 •

edited

Loading

fmease commented Oct 12, 2024 •

edited

Loading