mirror of
https://github.com/rust-lang/rust.git
synced 2026-07-26 17:42:22 -04:00
Nicholas Nethercote
eef3ae7817
For types, rustdoc produces different impl orderings in the sidebar vs.
the main section.
E.g. for `std::cell::UnsafeCell` the "Trait Implementations" sidebar
order is this:
```
!Freeze
!RefUnwindSafe
!Sync
CoerceUnsized<UnsafeCell<U>>
Debug
Default
DispatchFromDyn<UnsafeCell<U>>
From<T>
```
The primary sort is on polarity, and the secondary sort is alphabetical.
Makes sense.
The main section order is this:
```
impl<T> Debug for UnsafeCell<T>
impl<T> Default for UnsafeCell<T>
impl<T> From<T> for UnsafeCell<T>
impl<T, U> CoerceUnsized<UnsafeCell<U>> for UnsafeCell<T>
impl<T, U> DispatchFromDyn<UnsafeCell<U>> for UnsafeCell<T>
impl<T> !Freeze for UnsafeCell<T>
impl<T> !RefUnwindSafe for UnsafeCell<T>
impl<T> !Sync for UnsafeCell<T>
```
This strange ordering occurs because the entries are sorted on the
generated HTML. Impls with methods (the first three) come first because
they start with a `<details>` tag while the others start with a
`<section>` tag. After that, the order depends on a section id of the
form `impl-{trait}-for-{type}` that doesn't include the polarity, which
is why the secondary ordering is alphabetical but ignores the `!`.
The sidebar ordering is the better of the two. This commit changes the
main section to use the same ordering as the sidebar. This involves
creating a new function `impl_trait_key` shared between the two parts.
The tests present here are used to test the generated HTML from rustdoc. The goal is to prevent unsound/unexpected GUI changes.
This is using the browser-ui-test framework to do so. It works as follows:
It wraps puppeteer to send commands to a web browser in order to navigate and test what's being currently displayed in the web page.
You can find more information and its documentation in its repository.
If you need to have more information on the tests run, you can use --test-args:
$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --debug
If you don't want to run in headless mode (helpful to debug sometimes), you can use
--no-headless:
$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --no-headless
To see the supported options, use --help.