docs: Various linking / formatting fixes.

Also, this enables `clippy::doc_markdown` in the 3 crates to
help catch more of these in the future.

.clippy.toml

@@ -0,0 +1 @@
+doc-valid-idents = ["WebGPU", ".."]

crates/encoding/src/config.rs

@@ -21,7 +21,7 @@ const CLIP_REDUCE_WG: u32 = 256;
 
 /// Counters for tracking dynamic allocation on the GPU.
 ///
-/// This must be kept in sync with the struct in shader/shared/bump.wgsl
+/// This must be kept in sync with the struct in `shader/shared/bump.wgsl`
 #[derive(Clone, Copy, Debug, Default, Zeroable, Pod)]
 #[repr(C)]
 pub struct BumpAllocators {
@@ -39,7 +39,7 @@ pub struct BumpAllocators {
 
 /// Storage of indirect dispatch size values.
 ///
-/// The original plan was to reuse BumpAllocators, but the WebGPU compatible
+/// The original plan was to reuse [`BumpAllocators`], but the WebGPU compatible
 /// usage list rules forbid that being used as indirect counts while also
 /// bound as writable.
 #[derive(Clone, Copy, Debug, Default, Zeroable, Pod)]
@@ -54,7 +54,7 @@ pub struct IndirectCount {
 /// Uniform render configuration data used by all GPU stages.
 ///
 /// This data structure must be kept in sync with the definition in
-/// shaders/shared/config.wgsl.
+/// `shaders/shared/config.wgsl`.
 #[derive(Clone, Copy, Debug, Default, Zeroable, Pod)]
 #[repr(C)]
 pub struct ConfigUniform {
@@ -70,13 +70,13 @@ pub struct ConfigUniform {
     pub base_color: u32,
     /// Layout of packed scene data.
     pub layout: Layout,
-    /// Size of binning buffer allocation (in u32s).
+    /// Size of binning buffer allocation (in `u32`s).
     pub binning_size: u32,
-    /// Size of tile buffer allocation (in Tiles).
+    /// Size of tile buffer allocation (in [`Tile`]s).
     pub tiles_size: u32,
-    /// Size of segment buffer allocation (in PathSegments).
+    /// Size of segment buffer allocation (in [`PathSegment`]s).
     pub segments_size: u32,
-    /// Size of per-tile command list buffer allocation (in u32s).
+    /// Size of per-tile command list buffer allocation (in `u32`s).
     pub ptcl_size: u32,
 }
 

crates/encoding/src/lib.rs

@@ -3,6 +3,8 @@
 
 //! Raw scene encoding.
 
+#![warn(clippy::doc_markdown)]
+
 mod binning;
 mod clip;
 mod config;

crates/encoding/src/math.rs

@@ -78,10 +78,10 @@ pub fn point_to_f32(point: kurbo::Point) -> [f32; 2] {
 }
 
 /// Converts an f32 to IEEE-754 binary16 format represented as the bits of a u16.
-/// This implementation was adapted from Fabian Giesen's float_to_half_fast3()
-/// function which can be found at https://gist.github.com/rygorous/2156668#file-gistfile1-cpp-L285
+/// This implementation was adapted from Fabian Giesen's `float_to_half_fast3`()
+/// function which can be found at <https://gist.github.com/rygorous/2156668#file-gistfile1-cpp-L285>
 ///
-/// TODO: We should consider adopting https://crates.io/crates/half as a dependency since it nicely
+/// TODO: We should consider adopting <https://crates.io/crates/half> as a dependency since it nicely
 /// wraps native ARM and x86 instructions for floating-point conversion.
 #[allow(unused)] // for now
 pub(crate) fn f32_to_f16(val: f32) -> u16 {

crates/encoding/src/path.rs

@@ -241,17 +241,17 @@ pub struct PathTag(pub u8);
 impl PathTag {
     /// 32-bit floating point line segment.
     ///
-    /// This is equivalent to (PathSegmentType::LINE_TO | PathTag::F32_BIT).
+    /// This is equivalent to `(PathSegmentType::LINE_TO | PathTag::F32_BIT)`.
     pub const LINE_TO_F32: Self = Self(0x9);
 
     /// 32-bit floating point quadratic segment.
     ///
-    /// This is equivalent to (PathSegmentType::QUAD_TO | PathTag::F32_BIT).
+    /// This is equivalent to `(PathSegmentType::QUAD_TO | PathTag::F32_BIT)`.
     pub const QUAD_TO_F32: Self = Self(0xa);
 
     /// 32-bit floating point cubic segment.
     ///
-    /// This is equivalent to (PathSegmentType::CUBIC_TO | PathTag::F32_BIT).
+    /// This is equivalent to `(PathSegmentType::CUBIC_TO | PathTag::F32_BIT)`.
     pub const CUBIC_TO_F32: Self = Self(0xb);
 
     /// 16-bit integral line segment.
@@ -279,7 +279,7 @@ impl PathTag {
     /// Bit that marks a segment that is the end of a subpath.
     const SUBPATH_END_BIT: u8 = 0x4;
 
-    /// Mask for bottom 3 bits that contain the [PathSegmentType].
+    /// Mask for bottom 3 bits that contain the [`PathSegmentType`].
     const SEGMENT_MASK: u8 = 0x3;
 
     /// Returns true if the tag is a segment.
@@ -580,7 +580,7 @@ impl<'a> PathEncoder<'a> {
 
     /// Completes path encoding and returns the actual number of encoded segments.
     ///
-    /// If `insert_path_marker` is true, encodes the [PathTag::PATH] tag to signify
+    /// If `insert_path_marker` is true, encodes the [`PathTag::PATH`] tag to signify
     /// the end of a complete path object. Setting this to false allows encoding
     /// multiple paths with differing transforms for a single draw object.
     pub fn finish(mut self, insert_path_marker: bool) -> u32 {

crates/shaders/src/lib.rs

@@ -1,6 +1,8 @@
 // Copyright 2023 The Vello authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+#![warn(clippy::doc_markdown)]
+
 mod types;
 
 #[cfg(feature = "compile")]

src/engine.rs

@@ -151,7 +151,7 @@ impl Recording {
     /// Do an indirect dispatch.
     ///
     /// Dispatch a compute shader where the size is determined dynamically.
-    /// The `buf` argument contains the dispatch size, 3 u32 values beginning
+    /// The `buf` argument contains the dispatch size, 3 `u32` values beginning
     /// at the given byte `offset`.
     #[allow(unused)]
     pub fn dispatch_indirect<R>(

src/lib.rs

@@ -14,6 +14,8 @@
 //
 // Also licensed under MIT license, at your choice.
 
+#![warn(clippy::doc_markdown)]
+
 mod cpu_dispatch;
 mod cpu_shader;
 mod engine;
@@ -49,7 +51,7 @@ pub use shaders::FullShaders;
 #[cfg(feature = "wgpu")]
 use wgpu_engine::{ExternalResource, WgpuEngine};
 
-/// Temporary export, used in with_winit for stats
+/// Temporary export, used in `with_winit` for stats
 pub use vello_encoding::BumpAllocators;
 #[cfg(feature = "wgpu")]
 use wgpu::{Device, Queue, SurfaceTexture, TextureFormat, TextureView};
@@ -172,7 +174,7 @@ impl Renderer {
     /// Renders a scene to the target texture.
     ///
     /// The texture is assumed to be of the specified dimensions and have been created with
-    /// the [wgpu::TextureFormat::Rgba8Unorm] format and the [wgpu::TextureUsages::STORAGE_BINDING]
+    /// the [`wgpu::TextureFormat::Rgba8Unorm`] format and the [`wgpu::TextureUsages::STORAGE_BINDING`]
     /// flag set.
     pub fn render_to_texture(
         &mut self,
@@ -284,7 +286,7 @@ impl Renderer {
     /// Renders a scene to the target texture.
     ///
     /// The texture is assumed to be of the specified dimensions and have been created with
-    /// the [wgpu::TextureFormat::Rgba8Unorm] format and the [wgpu::TextureUsages::STORAGE_BINDING]
+    /// the [`wgpu::TextureFormat::Rgba8Unorm`] format and the [`wgpu::TextureUsages::STORAGE_BINDING`]
     /// flag set.
     ///
     /// The return value is the value of the `BumpAllocators` in this rendering, which is currently used
@@ -349,7 +351,7 @@ impl Renderer {
         Ok(bump)
     }
 
-    /// See [Self::render_to_surface]
+    /// See [`Self::render_to_surface`]
     pub async fn render_to_surface_async(
         &mut self,
         device: &Device,

src/mask.rs

@@ -30,7 +30,7 @@ fn one_mask(slope: f64, mut translation: f64, is_pos: bool) -> u8 {
 
 /// Make a lookup table of half-plane masks.
 ///
-/// The table is organized into two blocks each with MASK_HEIGHT/2 slopes.
+/// The table is organized into two blocks each with `MASK_HEIGHT/2` slopes.
 /// The first block is negative slopes (x decreases as y increates),
 /// the second as positive.
 pub fn make_mask_lut() -> Vec<u8> {
@@ -77,7 +77,7 @@ fn one_mask_16(slope: f64, mut translation: f64, is_pos: bool) -> u16 {
 
 /// Make a lookup table of half-plane masks.
 ///
-/// The table is organized into two blocks each with MASK16_HEIGHT/2 slopes.
+/// The table is organized into two blocks each with `MASK16_HEIGHT/2` slopes.
 /// The first block is negative slopes (x decreases as y increates),
 /// the second as positive.
 pub fn make_mask_lut_16() -> Vec<u8> {