Enable the doc_markdown clippy lint (#3457)

# Objective

CI should check for missing backticks in doc comments.

Fixes #3435

## Solution

`clippy` has a lint for this: `doc_markdown`. This enables that lint in the CI script.

Of course, enabling this lint in CI causes a bunch of lint errors, so I've gone through and fixed all of them. This was a huge edit that touched a ton of files, so I split the PR up by crate.

When all of the following are merged, the CI should pass and this can be merged.

+ [x] #3467
+ [x] #3468
+ [x] #3470 
+ [x] #3469
+ [x] #3471 
+ [x] #3472 
+ [x] #3473 
+ [x] #3474 
+ [x] #3475 
+ [x] #3476 
+ [x] #3477 
+ [x] #3478 
+ [x] #3479 
+ [x] #3480 
+ [x] #3481 
+ [x] #3482 
+ [x] #3483 
+ [x] #3484 
+ [x] #3485 
+ [x] #3486

Author: mfdorst

clippy.toml

@@ -0,0 +1 @@
+doc-valid-idents = ["sRGB", "NaN", "iOS", "glTF", "GitHub", "WebGPU"]

crates/bevy_app/src/plugin.rs

@@ -15,5 +15,6 @@ pub trait Plugin: Any + Send + Sync {
 }
 
 /// Type representing an unsafe function that returns a mutable pointer to a [`Plugin`].
-/// Used for dynamically loading plugins. See bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin
+/// Used for dynamically loading plugins. See
+/// `bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin`
 pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin;

crates/bevy_asset/src/assets.rs

@@ -47,17 +47,17 @@ impl<T: Asset> Debug for AssetEvent<T> {
 
 /// Stores Assets of a given type and tracks changes to them.
 ///
-/// Each asset is mapped by a unique [HandleId](crate::HandleId), allowing any [Handle](crate::Handle)
-/// with the same HandleId to access it. These assets remain loaded for as long as a Strong handle
-/// to that asset exists.
+/// Each asset is mapped by a unique [`HandleId`], allowing any [`Handle`] with the same
+/// [`HandleId`] to access it. These assets remain loaded for as long as a Strong handle to that
+/// asset exists.
 ///
 /// To store a reference to an asset without forcing it to stay loaded, you can use a Weak handle.
-/// To make a Weak handle a Strong one, use [Assets::get_handle](crate::Assets::get_handle) or pass
-/// the Assets collection into the handle's [make_strong](crate::Handle::make_strong) method.
-///
-/// Remember, if there are no Strong handles for an asset (i.e. they have all been dropped), the asset
-/// will unload. Make sure you always have a Strong handle when you want to keep an asset loaded!
+/// To make a Weak handle a Strong one, use [`Assets::get_handle`] or pass the `Assets` collection
+/// into the handle's [`make_strong`](Handle::make_strong) method.
 ///
+/// Remember, if there are no Strong handles for an asset (i.e. they have all been dropped), the
+/// asset will unload. Make sure you always have a Strong handle when you want to keep an asset
+/// loaded!
 #[derive(Debug)]
 pub struct Assets<T: Asset> {
     assets: HashMap<HandleId, T>,
@@ -92,7 +92,7 @@ impl<T: Asset> Assets<T> {
     /// Unless there exists another Strong handle for this asset, it's advised to use the returned
     /// Strong handle. Not doing so may result in the unexpected release of the asset.
     ///
-    /// See [set_untracked](Assets::set_untracked) for more info.
+    /// See [`set_untracked`](Assets::set_untracked) for more info.
     #[must_use = "not using the returned strong handle may result in the unexpected release of the asset"]
     pub fn set<H: Into<HandleId>>(&mut self, handle: H, asset: T) -> Handle<T> {
         let id: HandleId = handle.into();
@@ -102,8 +102,8 @@ impl<T: Asset> Assets<T> {
 
     /// Add/modify the asset pointed to by the given handle.
     ///
-    /// If an asset already exists with the given HandleId, it will be modified. Otherwise the new asset
-    /// will be inserted.
+    /// If an asset already exists with the given [`HandleId`], it will be modified. Otherwise the
+    /// new asset will be inserted.
     ///
     /// # Events
     /// * [`AssetEvent::Created`]: Sent if the asset did not yet exist with the given handle
@@ -124,7 +124,7 @@ impl<T: Asset> Assets<T> {
     /// Get the asset for the given handle.
     ///
     /// This is the main method for accessing asset data from an [Assets] collection. If you need
-    /// mutable access to the asset, use [get_mut](Assets::get_mut).
+    /// mutable access to the asset, use [`get_mut`](Assets::get_mut).
     pub fn get<H: Into<HandleId>>(&self, handle: H) -> Option<&T> {
         self.assets.get(&handle.into())
     }
@@ -190,7 +190,7 @@ impl<T: Asset> Assets<T> {
         self.assets.iter_mut().map(|(k, v)| (*k, v))
     }
 
-    /// Get an iterator over all HandleIds in the collection.
+    /// Get an iterator over all [`HandleId`]'s in the collection.
     pub fn ids(&self) -> impl Iterator<Item = HandleId> + '_ {
         self.assets.keys().cloned()
     }

crates/bevy_crevice/src/lib.rs

@@ -3,7 +3,8 @@
     clippy::needless_update,
     clippy::len_without_is_empty,
     clippy::needless_range_loop,
-    clippy::all
+    clippy::all,
+    clippy::doc_markdown
 )]
 /*!
 [![GitHub CI Status](https://github.com/LPGhatguy/crevice/workflows/CI/badge.svg)](https://github.com/LPGhatguy/crevice/actions)

crates/bevy_internal/src/lib.rs

@@ -94,7 +94,7 @@ pub mod core_pipeline {
 
 #[cfg(feature = "bevy_gilrs")]
 pub mod gilrs {
-    //! Bevy interface with GilRs - Game Input Library for Rust to handle gamepad inputs
+    //! Bevy interface with `GilRs` - "Game Input Library for Rust" - to handle gamepad inputs.
     pub use bevy_gilrs::*;
 }
 

crates/bevy_render/src/options.rs

@@ -55,7 +55,7 @@ impl Default for WgpuOptions {
     }
 }
 
-/// Get a features/limits priority from the environment variable WGPU_OPTIONS_PRIO
+/// Get a features/limits priority from the environment variable `WGPU_OPTIONS_PRIO`
 pub fn options_priority_from_env() -> Option<WgpuOptionsPriority> {
     Some(
         match std::env::var("WGPU_OPTIONS_PRIO")

crates/bevy_transform/src/components/global_transform.rs

@@ -175,7 +175,7 @@ impl GlobalTransform {
         self.rotation * Vec3::Z
     }
 
-    /// Equivalent to [`-local_z()`][[GlobalTransform::local_z]
+    /// Equivalent to [`-local_z()`][GlobalTransform::local_z]
     #[inline]
     pub fn forward(&self) -> Vec3 {
         -self.local_z()

crates/bevy_window/src/window.rs

@@ -256,7 +256,7 @@ impl Window {
     }
 
     /// The requested window client area width in logical pixels from window
-    /// creation or the last call to [set_resolution](Window::set_resolution).
+    /// creation or the last call to [`set_resolution`](Window::set_resolution).
     ///
     /// This may differ from the actual width depending on OS size limits and
     /// the scaling factor for high DPI monitors.
@@ -266,7 +266,7 @@ impl Window {
     }
 
     /// The requested window client area height in logical pixels from window
-    /// creation or the last call to [set_resolution](Window::set_resolution).
+    /// creation or the last call to [`set_resolution`](Window::set_resolution).
     ///
     /// This may differ from the actual width depending on OS size limits and
     /// the scaling factor for high DPI monitors.
@@ -403,7 +403,7 @@ impl Window {
     }
 
     /// The window scale factor as reported by the window backend.
-    /// This value is unaffected by scale_factor_override.
+    /// This value is unaffected by [`scale_factor_override`](Window::scale_factor_override).
     #[inline]
     pub fn backend_scale_factor(&self) -> f64 {
         self.backend_scale_factor

tools/ci/src/main.rs

@@ -13,7 +13,7 @@ fn main() {
 
     // See if clippy has any complaints.
     // - Type complexity must be ignored because we use huge templates for queries
-    cmd!("cargo clippy --workspace --all-targets --all-features -- -D warnings -A clippy::type_complexity")
+    cmd!("cargo clippy --workspace --all-targets --all-features -- -D warnings -A clippy::type_complexity -W clippy::doc_markdown")
         .run()
         .expect("Please fix clippy errors in output above.");