From d39f6780a757074be1ef4acb04ee4155ec13b3d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Capucho?= Date: Fri, 30 Jul 2021 19:11:31 +0100 Subject: [PATCH] Documentation fixes --- src/back/dot/mod.rs | 2 +- src/back/glsl/mod.rs | 6 +- src/back/hlsl/conv.rs | 3 +- src/back/hlsl/help.rs | 118 ++++++++++++++++++++------------------ src/back/hlsl/keywords.rs | 6 +- src/back/hlsl/writer.rs | 2 +- src/back/spv/mod.rs | 4 +- src/back/wgsl/writer.rs | 9 ++- 8 files changed, 79 insertions(+), 71 deletions(-) diff --git a/src/back/dot/mod.rs b/src/back/dot/mod.rs index 2659ddc49c..c45e1b3095 100644 --- a/src/back/dot/mod.rs +++ b/src/back/dot/mod.rs @@ -134,7 +134,7 @@ fn name(option: &Option) -> &str { } } -/// set39 color scheme from https://graphviz.org/doc/info/colors.html +/// set39 color scheme from const COLORS: &[&str] = &[ "white", // pattern starts at 1 "#8dd3c7", "#ffffb3", "#bebada", "#fb8072", "#80b1d3", "#fdb462", "#b3de69", "#fccde5", diff --git a/src/back/glsl/mod.rs b/src/back/glsl/mod.rs index 5777134c8e..e4a2e86e82 100644 --- a/src/back/glsl/mod.rs +++ b/src/back/glsl/mod.rs @@ -647,7 +647,8 @@ impl<'a, W: Write> Writer<'a, W> { /// # Panics /// - If type is either a image, a sampler, a pointer, or a struct /// - If it's an Array with a [`ArraySize::Constant`](crate::ArraySize::Constant) with a - /// constant that isn't [`Uint`](crate::ConstantInner::Uint) + /// constant that isn't a [`Scalar`](crate::ConstantInner::Scalar) or if the + /// scalar value isn't an [`Sint`](crate::ScalarValue::Sint) or [`Uint`](crate::ScalarValue::Uint) fn write_value_type(&mut self, inner: &TypeInner) -> BackendResult { match *inner { // Scalars are simple we just get the full name from `glsl_scalar` @@ -712,7 +713,8 @@ impl<'a, W: Write> Writer<'a, W> { /// # Panics /// - If type is either a image or sampler /// - If it's an Array with a [`ArraySize::Constant`](crate::ArraySize::Constant) with a - /// constant that isn't [`Uint`](crate::ConstantInner::Uint) + /// constant that isn't a [`Scalar`](crate::ConstantInner::Scalar) or if the + /// scalar value isn't an [`Sint`](crate::ScalarValue::Sint) or [`Uint`](crate::ScalarValue::Uint) fn write_type(&mut self, ty: Handle) -> BackendResult { match self.module.types[ty].inner { // glsl has no pointer types so just write types as normal and loads are skipped diff --git a/src/back/hlsl/conv.rs b/src/back/hlsl/conv.rs index 1d56a08d95..2291589731 100644 --- a/src/back/hlsl/conv.rs +++ b/src/back/hlsl/conv.rs @@ -11,7 +11,8 @@ impl crate::ScalarKind { } /// Helper function that returns scalar related strings - /// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-scalar + /// + /// pub(super) fn to_hlsl_str(self, width: crate::Bytes) -> Result<&'static str, Error> { match self { Self::Sint => Ok("int"), diff --git a/src/back/hlsl/help.rs b/src/back/hlsl/help.rs index d72c7a2425..a8147aa5a2 100644 --- a/src/back/hlsl/help.rs +++ b/src/back/hlsl/help.rs @@ -1,25 +1,28 @@ -// Important note about `Expression::ImageQuery`/`Expression::ArrayLength` and hlsl backend: -// Due to implementation of `GetDimensions` function in hlsl (https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-to-getdimensions) -// backend can't work with it as an expression. -// Instead, it generates a unique wrapped function per `Expression::ImageQuery`, based on texure info and query function. -// See `WrappedImageQuery` struct that represents a unique function and will be generated before writing all statements and expressions. -// This allowed to works with `Expression::ImageQuery` as expression and write wrapped function. -// -// For example: -// ```wgsl -// let dim_1d = textureDimensions(image_1d); -// ``` -// -// ```hlsl -// int NagaDimensions1D(Texture1D) -// { -// uint4 ret; -// image_1d.GetDimensions(ret.x); -// return ret.x; -// } -// -// int dim_1d = NagaDimensions1D(image_1d); -// ``` +//! Helpers for the hlsl backend +//! +//! Important note about `Expression::ImageQuery`/`Expression::ArrayLength` and hlsl backend: +//! +//! Due to implementation of `GetDimensions` function in hlsl () +//! backend can't work with it as an expression. +//! Instead, it generates a unique wrapped function per `Expression::ImageQuery`, based on texure info and query function. +//! See `WrappedImageQuery` struct that represents a unique function and will be generated before writing all statements and expressions. +//! This allowed to works with `Expression::ImageQuery` as expression and write wrapped function. +//! +//! For example: +//! ```wgsl +//! let dim_1d = textureDimensions(image_1d); +//! ``` +//! +//! ```hlsl +//! int NagaDimensions1D(Texture1D) +//! { +//! uint4 ret; +//! image_1d.GetDimensions(ret.x); +//! return ret.x; +//! } +//! +//! int dim_1d = NagaDimensions1D(image_1d); +//! ``` use super::{super::FunctionCtx, BackendResult}; use crate::arena::Handle; @@ -38,37 +41,37 @@ pub(super) struct WrappedImageQuery { pub(super) query: ImageQuery, } -// HLSL backend requires its own `ImageQuery` enum. -// It is used inside `WrappedImageQuery` and should be unique per ImageQuery function. -// IR version can't be unique per function, because it's store mipmap level as an expression. -// -// For example: -// ```wgsl -// let dim_cube_array_lod = textureDimensions(image_cube_array, 1); -// let dim_cube_array_lod2 = textureDimensions(image_cube_array, 1); -// ``` -// -// ```ir -// ImageQuery { -// image: [1], -// query: Size { -// level: Some( -// [1], -// ), -// }, -// }, -// ImageQuery { -// image: [1], -// query: Size { -// level: Some( -// [2], -// ), -// }, -// }, -// ``` -// -// HLSL should generate only 1 function for this case. -// +/// HLSL backend requires its own `ImageQuery` enum. +/// +/// It is used inside `WrappedImageQuery` and should be unique per ImageQuery function. +/// IR version can't be unique per function, because it's store mipmap level as an expression. +/// +/// For example: +/// ```wgsl +/// let dim_cube_array_lod = textureDimensions(image_cube_array, 1); +/// let dim_cube_array_lod2 = textureDimensions(image_cube_array, 1); +/// ``` +/// +/// ```ir +/// ImageQuery { +/// image: [1], +/// query: Size { +/// level: Some( +/// [1], +/// ), +/// }, +/// }, +/// ImageQuery { +/// image: [1], +/// query: Size { +/// level: Some( +/// [2], +/// ), +/// }, +/// }, +/// ``` +/// +/// HLSL should generate only 1 function for this case. #[derive(Clone, Copy, Debug, Hash, Eq, Ord, PartialEq, PartialOrd)] pub(super) enum ImageQuery { Size, @@ -141,7 +144,8 @@ impl<'a, W: Write> super::Writer<'a, W> { } /// Helper function that write wrapped function for `Expression::ArrayLength` - /// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/sm5-object-rwbyteaddressbuffer-getdimensions + /// + /// pub(super) fn write_wrapped_array_length_function( &mut self, module: &crate::Module, @@ -221,7 +225,8 @@ impl<'a, W: Write> super::Writer<'a, W> { } /// Helper function that write wrapped function for `Expression::ImageQuery` - /// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-to-getdimensions + /// + /// pub(super) fn write_wrapped_image_query_function( &mut self, module: &crate::Module, @@ -338,7 +343,8 @@ impl<'a, W: Write> super::Writer<'a, W> { } /// Helper function that write wrapped function for `Expression::ImageQuery` and `Expression::ArrayLength` - /// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-to-getdimensions + /// + /// pub(super) fn write_wrapped_functions( &mut self, module: &crate::Module, diff --git a/src/back/hlsl/keywords.rs b/src/back/hlsl/keywords.rs index 1c19c5112a..e322c98af1 100644 --- a/src/back/hlsl/keywords.rs +++ b/src/back/hlsl/keywords.rs @@ -1,6 +1,6 @@ -/// HLSL Reserved Words -/// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-appendix-keywords -/// https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-appendix-reserved-words +//! HLSL Reserved Words +//! - +//! - pub const RESERVED: &[&str] = &[ "AppendStructuredBuffer", "asm", diff --git a/src/back/hlsl/writer.rs b/src/back/hlsl/writer.rs index 2ef57b266c..faa2212b59 100644 --- a/src/back/hlsl/writer.rs +++ b/src/back/hlsl/writer.rs @@ -1734,7 +1734,7 @@ impl<'a, W: fmt::Write> super::Writer<'a, W> { Ok(()) } - /// Helper method used to write [`ScalarValue`](ScalarValue) + /// Helper method used to write [`ScalarValue`](crate::ScalarValue) /// /// # Notes /// Adds no trailing or leading whitespace diff --git a/src/back/spv/mod.rs b/src/back/spv/mod.rs index 0dcb975679..3666211c74 100644 --- a/src/back/spv/mod.rs +++ b/src/back/spv/mod.rs @@ -268,7 +268,7 @@ enum Dimension { Matrix, } -/// A map from evaluated [`Expression`s] to their SPIR-V ids. +/// A map from evaluated [`Expression`](crate::Expression)s to their SPIR-V ids. /// /// When we emit code to evaluate a given `Expression`, we record the /// SPIR-V id of its value here, under its `Handle` index. @@ -343,7 +343,7 @@ struct BlockContext<'w> { /// [`ir_function`](BlockContext::ir_function). fun_info: &'w crate::valid::FunctionInfo, - /// The [`back::spv::Function`] to which we are contributing SPIR-V instructions. + /// The [`spv::Function`](Function) to which we are contributing SPIR-V instructions. function: &'w mut Function, /// SPIR-V ids for expressions we've evaluated. diff --git a/src/back/wgsl/writer.rs b/src/back/wgsl/writer.rs index 20d0cce1df..3a343d6027 100644 --- a/src/back/wgsl/writer.rs +++ b/src/back/wgsl/writer.rs @@ -9,8 +9,7 @@ use std::fmt::Write; /// Shorthand result used internally by the backend type BackendResult = Result<(), Error>; -/// WGSL attribute -/// https://gpuweb.github.io/gpuweb/wgsl/#attributes +/// WGSL [attribute](https://gpuweb.github.io/gpuweb/wgsl/#attributes) enum Attribute { Binding(u32), Block, @@ -137,7 +136,7 @@ impl Writer { Ok(()) } - /// Helper method used to write [`ScalarValue`](ScalarValue) + /// Helper method used to write [`ScalarValue`](crate::ScalarValue) /// /// # Notes /// Adds no trailing or leading whitespace @@ -179,8 +178,8 @@ impl Writer { Ok(()) } - /// Helper method used to write structs - /// https://gpuweb.github.io/gpuweb/wgsl/#functions + /// Helper method used to write + /// [functions](https://gpuweb.github.io/gpuweb/wgsl/#functions) /// /// # Notes /// Ends in a newline