Skip to content

rustdoc: improve word break opportunities for narrow screens #93538

@jsha

Description

@jsha
Contributor

On narrow screens our method signatures often wrap horribly, like this example that wraps right in the middle of a -> return arrow:

image

To fix that specific issue, we can wrap return arrows in a <span> and style that span with white-space: nowrap. There's a similar issue where the browser will break &[T] between the & and the [. We should use the same trick there to prevent breaking.

Also, the browser will never consider a parenthesis wedged between two words to be a word break opportunity. For instance, in fn foo(bar: Baz), the browser will never break between ( and bar. That's actually one of our optimal break locations; it's where rustfmt would break the word. We can tell the browser that's an available option by inserting a <wbr> tag.

Also, when we do have to break up a signature, we'd prefer to keep each parameter name on the same line as its type if possible (again, mimicking rustfmt style). We can achieve this by inserting an &nbsp; between parameter names and types. For instance bar:&nbsp;Baz. We should also use &nbsp; as the space between mut and Bar in &mut Bar. Note that this may be a little hard because that space is added by print_with_space, and the output of print_with_space is used in both HTML and non-HTML contexts.

Activity

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
A-rustdoc-uiArea: Rustdoc UI (generated HTML)
on Feb 1, 2022
jsha

jsha commented on Feb 6, 2022

@jsha
ContributorAuthor

Another possibility: We could do like pkg.go.dev does (e.g. https://pkg.go.dev/crypto/tls#ClientHelloInfo.SupportsCertificate), and set these CSS properties on the method headings:

white-space: pre-wrap;
word-break: break-all;
word-wrap: break-word;

That would cause us to always put as much text as possible on a line, and break right at the end. That would still, allow breaking in the middle of a return arrow, or other awkward breaks. But it might be clearer that a break happened, since the pattern is consistent and the line is filled.

Also worth noting: One of the confusing things in the screenshot above is the collision with the source link, which will be fixed in #93537.

Enyium

Enyium commented on Aug 3, 2024

@Enyium

I wondered why text in the right column of this documentation has strange line breaks in the middle of words like "to show th<br>e Slint documentation" or "for red, gr<br>een, blue". The respective <div>s have the CSS word-break: break-all; applied, which rustdoc seems to be responsible for. At least for me in a desktop browser, I'm against this in favor of regular line breaks between words.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-rustdoc-uiArea: Rustdoc UI (generated HTML)T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @jsha@Enyium

        Issue actions

          rustdoc: improve word break opportunities for narrow screens · Issue #93538 · rust-lang/rust