From 091d7869cfd5b8b1d776b4acecc985571727ff03 Mon Sep 17 00:00:00 2001
From: Augusto Hack <hack.augusto@gmail.com>
Date: Mon, 19 Feb 2024 12:23:12 +0100
Subject: [PATCH] Docs surface creation no longer unsafe (#5265)

* doc: as of #4597 surface creation is no longer unsafe

* doc: extend documentation of the include_wgsl macro
---
 CHANGELOG.md       |  1 +
 wgpu/src/lib.rs    |  2 +-
 wgpu/src/macros.rs | 11 ++++++++++-
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index afaff5bb98..98ef0492ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -74,6 +74,7 @@ Bottom level categories:
 ### Documentation
 - Fix link in `wgpu::Instance::create_surface` documentation. By @HexoKnight in [#5280](https://github.com/gfx-rs/wgpu/pull/5280).
 - Fix typo in `wgpu::CommandEncoder::clear_buffer` documentation. By @PWhiddy in [#5281](https://github.com/gfx-rs/wgpu/pull/5281).
+- `Surface` configuration incorrectly claimed that `wgpu::Instance::create_surface` was unsafe. By @hackaugusto in [#5265](https://github.com/gfx-rs/wgpu/pull/5265).
 
 
 ### Bug Fixes
diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs
index 11eceb5f93..d98c0e3d25 100644
--- a/wgpu/src/lib.rs
+++ b/wgpu/src/lib.rs
@@ -403,7 +403,7 @@ static_assertions::assert_impl_all!(SurfaceConfiguration: Send, Sync);
 /// Handle to a presentable surface.
 ///
 /// A `Surface` represents a platform-specific surface (e.g. a window) onto which rendered images may
-/// be presented. A `Surface` may be created with the unsafe function [`Instance::create_surface`].
+/// be presented. A `Surface` may be created with the function [`Instance::create_surface`].
 ///
 /// This type is unique to the Rust API of `wgpu`. In the WebGPU specification,
 /// [`GPUCanvasContext`](https://gpuweb.github.io/gpuweb/#canvas-context)
diff --git a/wgpu/src/macros.rs b/wgpu/src/macros.rs
index fc3560e01c..f1a15e764e 100644
--- a/wgpu/src/macros.rs
+++ b/wgpu/src/macros.rs
@@ -78,7 +78,16 @@ macro_rules! include_spirv_raw {
     };
 }
 
-/// Macro to load a WGSL module statically.
+/// Load WGSL source code from a file at compile time.
+///
+/// The loaded path is relative to the path of the file containing the macro call, in the same way
+/// as [`include_str!`] operates.
+///
+/// ```ignore
+/// fn main() {
+///     let module: ShaderModuleDescriptor = include_wgsl!("shader.wgsl");
+/// }
+/// ```
 #[macro_export]
 macro_rules! include_wgsl {
     ($($token:tt)*) => {