From f5b78f1b43a9e8f979f98bf913896d6726f84c55 Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Thu, 2 Nov 2023 23:30:23 +0700 Subject: [PATCH] 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 | 1 + crates/encoding/src/config.rs | 14 +++++++------- crates/encoding/src/lib.rs | 2 ++ crates/encoding/src/math.rs | 6 +++--- crates/encoding/src/path.rs | 10 +++++----- crates/shaders/src/lib.rs | 2 ++ src/engine.rs | 2 +- src/lib.rs | 10 ++++++---- src/mask.rs | 4 ++-- 9 files changed, 29 insertions(+), 22 deletions(-) create mode 100644 .clippy.toml diff --git a/.clippy.toml b/.clippy.toml new file mode 100644 index 000000000..198f214bf --- /dev/null +++ b/.clippy.toml @@ -0,0 +1 @@ +doc-valid-idents = ["WebGPU", ".."] diff --git a/crates/encoding/src/config.rs b/crates/encoding/src/config.rs index 6f24925b8..ee48e59cb 100644 --- a/crates/encoding/src/config.rs +++ b/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, } diff --git a/crates/encoding/src/lib.rs b/crates/encoding/src/lib.rs index 9b61cc5bf..3dbdb52f8 100644 --- a/crates/encoding/src/lib.rs +++ b/crates/encoding/src/lib.rs @@ -3,6 +3,8 @@ //! Raw scene encoding. +#![warn(clippy::doc_markdown)] + mod binning; mod clip; mod config; diff --git a/crates/encoding/src/math.rs b/crates/encoding/src/math.rs index 822f43424..45b9fcfa9 100644 --- a/crates/encoding/src/math.rs +++ b/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 /// -/// TODO: We should consider adopting https://crates.io/crates/half as a dependency since it nicely +/// TODO: We should consider adopting 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 { diff --git a/crates/encoding/src/path.rs b/crates/encoding/src/path.rs index fb97f2d73..653bb6f50 100644 --- a/crates/encoding/src/path.rs +++ b/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 { diff --git a/crates/shaders/src/lib.rs b/crates/shaders/src/lib.rs index 1dacfbda4..645544e9e 100644 --- a/crates/shaders/src/lib.rs +++ b/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")] diff --git a/src/engine.rs b/src/engine.rs index a122e3537..2ed97e275 100644 --- a/src/engine.rs +++ b/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( diff --git a/src/lib.rs b/src/lib.rs index efbe74a95..c53b835c9 100644 --- a/src/lib.rs +++ b/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, diff --git a/src/mask.rs b/src/mask.rs index 61cacf0bc..0d0ce78b3 100644 --- a/src/mask.rs +++ b/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 { @@ -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 {