rustdoc skips first line of some list items, and incorrect clippy warning

[maia-s]

I tried this code (minimal reproduction lib.rs):

/// - [`SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER`]: the
///   `(__unsafe_unretained)` NSWindow associated with the window, if you want
///   to wrap an existing window.
/// - [`SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER`]: the `(__unsafe_unretained)`
///   NSView associated with the window, defaults to `[window contentView]`
pub fn a() {}

/// - [`SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER`]: the maximum texture width
///   and height
/// - [`SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`]: a (const [`SDL_PixelFormat`] *)
///   array of pixel formats, terminated with [`SDL_PIXELFORMAT_UNKNOWN`],
///   representing the available texture formats for this renderer.
pub fn b() {}

pub const SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER: () = ();
pub const SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER: () = ();

pub const SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER: () = ();
pub const SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER: () = ();
pub const SDL_PIXELFORMAT_UNKNOWN: () = ();
#[allow(non_camel_case_types)]
pub type SDL_PixelFormat = ();

When I run cargo doc on this, there are no warnings or errors, but the output is wrong. The first line of the first list item of a is missing, and the first line of the second list item of b is also missing.

If I run cargo clippy on the file it complains:

warning: doc list item without indentation
 --> src/lib.rs:3:5
  |
3 | ///   to wrap an existing window.
  |     ^^
  |
  = help: if this is supposed to be its own paragraph, add a blank line
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
  = note: `#[warn(clippy::doc_lazy_continuation)]` on by default
help: indent this line
  |
3 | ///                                                          to wrap an existing window.
  |       +++++++++++++++++++++++++++++++++++++++++++++++++++++++

warning: doc list item without indentation
  --> src/lib.rs:12:5
   |
12 | ///   representing the available texture formats for this renderer.
   |     ^^
   |
   = help: if this is supposed to be its own paragraph, add a blank line
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
   |
12 | ///                                                                                    representing the available texture formats for this renderer.
   |       +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

warning: `rustdocbug` (lib) generated 2 warnings

But this makes no sense. Those lines have the correct indentation, same as the previous lines. It seems to think there's a new sublist getting created at the end of the first lines, but I don't see why

Meta

rustc --version --verbose:

% rustc --version --verbose
rustc 1.82.0 (f6e511eec 2024-10-15)
binary: rustc
commit-hash: f6e511eec7342f59a25f7c0534f1dbea00d01b14
commit-date: 2024-10-15
host: aarch64-apple-darwin
release: 1.82.0
LLVM version: 19.1.1

% rustc +nightly --version --verbose
rustc 1.84.0-nightly (798fb83f7 2024-10-16)
binary: rustc
commit-hash: 798fb83f7d24e31b16acca113496f39ff168c143
commit-date: 2024-10-16
host: aarch64-apple-darwin
release: 1.84.0-nightly
LLVM version: 19.1.1

[maia-s]

If I remove the [] around SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER and SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER so those items aren't linked, the bug doesn't happen and clippy doesn't complain

[workingjubilee]

Thank you for discovering increasingly fascinating edge-cases.

[notriddle]

It does the same thing when I strip the /// prefix and copy it into GitHub or the commonmark dingus, which means this technically isn't a bug (except for Clippy's broken suggestion, which is a real bug). It is very misleading, though, and ought to produce a warning and suggested fix.

As a better workaround, write a collapsed link instead of a shortcut link:

- [`SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER`][]: the
  `(__unsafe_unretained)` NSWindow associated with the window, if you want
  to wrap an existing window.
- [`SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER`][]: the `(__unsafe_unretained)`
  NSView associated with the window, defaults to `[window contentView]`

• [SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER][]: the
  (__unsafe_unretained) NSWindow associated with the window, if you want
  to wrap an existing window.
• [SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER][]: the (__unsafe_unretained)
  NSView associated with the window, defaults to [window contentView]