Tidy up "platform-specifc" doc sections (#2356)

* Tidy up "platform-specific" doc sections

* Unrelated grammatical fix

* Subjective improvements

src/event.rs

@@ -277,16 +277,18 @@ pub enum WindowEvent<'a> {
 
     /// The keyboard modifiers have changed.
     ///
-    /// Platform-specific behavior:
+    /// ## Platform-specific
-    /// - **Web**: This API is currently unimplemented on the web. This isn't by design - it's an
+    ///
+    /// - **Web:** This API is currently unimplemented on the web. This isn't by design - it's an
     ///   issue, and it should get fixed - but it's the current state of the API.
     ModifiersChanged(ModifiersState),
 
-    /// An event from input method.
+    /// An event from an input method.
     ///
     /// **Note:** You have to explicitly enable this event using [`Window::set_ime_allowed`].
     ///
-    /// Platform-specific behavior:
+    /// ## Platform-specific
+    ///
     /// - **iOS / Android / Web:** Unsupported.
     Ime(Ime),
 
@@ -370,6 +372,8 @@ pub enum WindowEvent<'a> {
     /// Applications might wish to react to this to change the theme of the content of the window
     /// when the system changes the window theme.
     ///
+    /// ## Platform-specific
+    ///
     /// At the moment this is only supported on Windows.
     ThemeChanged(Theme),
 

src/event_loop.rs

@@ -146,6 +146,7 @@ pub enum ControlFlow {
     /// whether or not new events are available to process.
     ///
     /// ## Platform-specific
+    ///
     /// - **Web:** Events are queued and usually sent when `requestAnimationFrame` fires but sometimes
     ///   the events in the queue may be sent before the next `requestAnimationFrame` callback, for
     ///   example when the scaling of the page has changed. This should be treated as an implementation
@@ -171,8 +172,8 @@ pub enum ControlFlow {
     ///
     /// ## Platform-specific
     ///
-    /// - **Android / iOS / WASM**: The supplied exit code is unused.
+    /// - **Android / iOS / WASM:** The supplied exit code is unused.
-    /// - **Unix**: On most Unix-like platforms, only the 8 least significant bits will be used,
+    /// - **Unix:** On most Unix-like platforms, only the 8 least significant bits will be used,
     ///   which can cause surprises with negative exit values (`-42` would end up as `214`). See
     ///   [`std::process::exit`].
     ///
@@ -264,7 +265,7 @@ impl<T> EventLoop<T> {
     ///
     /// ## Platform-specific
     ///
-    /// - **X11 / Wayland**: The program terminates with exit code 1 if the display server
+    /// - **X11 / Wayland:** The program terminates with exit code 1 if the display server
     ///   disconnects.
     ///
     /// [`ControlFlow`]: crate::event_loop::ControlFlow
@@ -321,7 +322,7 @@ impl<T> EventLoopWindowTarget<T> {
     ///
     /// ## Platform-specific
     ///
-    /// - **Wayland / Windows / macOS / iOS / Android / Web**: Unsupported.
+    /// - **Wayland / Windows / macOS / iOS / Android / Web:** Unsupported.
     ///
     /// [`DeviceEvent`]: crate::event::DeviceEvent
     pub fn set_device_event_filter(&self, _filter: DeviceEventFilter) {

src/platform/run_return.rs

@@ -37,7 +37,7 @@ pub trait EventLoopExtRunReturn {
     ///
     /// ## Platform-specific
     ///
-    /// - **Unix-alikes** (**X11** or **Wayland**): This function returns `1` upon disconnection from
+    /// - **X11 / Wayland:** This function returns `1` upon disconnection from
     ///   the display server.
     fn run_return<F>(&mut self, event_handler: F) -> i32
     where

src/window.rs

@@ -203,20 +203,20 @@ impl WindowBuilder {
     ///
     /// ## Platform-specific
     ///
-    /// - **macOS**: The top left corner position of the window content, the
+    /// - **macOS:** The top left corner position of the window content, the
     ///   window's "inner" position. The window title bar will be placed above
     ///   it. The window will be positioned such that it fits on screen,
     ///   maintaining set `inner_size` if any.
     ///   If you need to precisely position the top left corner of the whole
     ///   window you have to use [`Window::set_outer_position`] after creating
     ///   the window.
-    /// - **Windows**: The top left corner position of the window title bar,
+    /// - **Windows:** The top left corner position of the window title bar,
     ///   the window's "outer" position.
     ///   There may be a small gap between this position and the window due to
     ///   the specifics of the Window Manager.
-    /// - **X11**: The top left corner of the window, the window's "outer"
+    /// - **X11:** The top left corner of the window, the window's "outer"
     ///   position.
-    /// - **Others**: Ignored.
+    /// - **Others:** Ignored.
     #[inline]
     pub fn with_position<P: Into<Position>>(mut self, position: P) -> Self {
         self.window.position = Some(position.into());
@@ -333,8 +333,9 @@ impl WindowBuilder {
     ///
     /// Possible causes of error include denied permission, incompatible system, and lack of memory.
     ///
-    /// Platform-specific behavior:
+    /// ## Platform-specific
-    /// - **Web**: The window is created but not inserted into the web page automatically. Please
+    ///
+    /// - **Web:** The window is created but not inserted into the web page automatically. Please
     ///   see the web platform module for more information.
     #[inline]
     pub fn build<T: 'static>(
@@ -359,8 +360,9 @@ impl Window {
     /// Error should be very rare and only occur in case of permission denied, incompatible system,
     ///  out of memory, etc.
     ///
-    /// Platform-specific behavior:
+    /// ## Platform-specific
-    /// - **Web**: The window is created but not inserted into the web page automatically. Please
+    ///
+    /// - **Web:** The window is created but not inserted into the web page automatically. Please
     ///   see the web platform module for more information.
     ///
     /// [`WindowBuilder::new().build(event_loop)`]: WindowBuilder::build
@@ -648,10 +650,7 @@ impl Window {
     ///
     /// This only has an effect on desktop platforms.
     ///
-    /// Due to a bug in XFCE, this has no effect on Xfwm.
+    /// - **X11:** Due to a bug in XFCE, this has no effect on Xfwm.
-    ///
-    /// ## Platform-specific
-    ///
     /// - **iOS / Android / Web:** Unsupported.
     ///
     /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
@@ -1176,10 +1175,12 @@ pub enum Theme {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum UserAttentionType {
     /// ## Platform-specific
+    ///
     /// - **macOS:** Bounces the dock icon until the application is in focus.
     /// - **Windows:** Flashes both the window and the taskbar button until the application is in focus.
     Critical,
     /// ## Platform-specific
+    ///
     /// - **macOS:** Bounces the dock icon once.
     /// - **Windows:** Flashes the taskbar button until the application is in focus.
     Informational,