From f035854dac7faad6660719f4d6f6a9f3bf468ea3 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Wed, 25 May 2022 17:10:20 -0700
Subject: [PATCH] Doc tweaks.

---
 src/front/wgsl/mod.rs |  3 +--
 src/span.rs           | 14 +++++++++-----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/front/wgsl/mod.rs b/src/front/wgsl/mod.rs
index 76a61e98ea..a7c1fdced6 100644
--- a/src/front/wgsl/mod.rs
+++ b/src/front/wgsl/mod.rs
@@ -1366,8 +1366,7 @@ impl ParseError {
         writer.into_string()
     }
 
-    /// Returns the 1-based line number and column of the first label in the
-    /// error message.
+    /// Returns a [`SourceLocation`] for the first label in the error message.
     pub fn location(&self, source: &str) -> Option<SourceLocation> {
         self.labels
             .get(0)
diff --git a/src/span.rs b/src/span.rs
index 1c2249c4a0..6f2583a5eb 100644
--- a/src/span.rs
+++ b/src/span.rs
@@ -60,8 +60,7 @@ impl Span {
         *self != Self::default()
     }
 
-    /// Returns the 1-based line number and column of the this span in
-    /// the provided source.
+    /// Return a [`SourceLocation`] for this span in the provided source.
     pub fn location(&self, source: &str) -> SourceLocation {
         let prefix = &source[..self.start as usize];
         let line_number = prefix.matches('\n').count() as u32 + 1;
@@ -86,10 +85,13 @@ impl From<Range<usize>> for Span {
     }
 }
 
-/// A human-readable representation for span, tailored for text source.
+/// A human-readable representation for a span, tailored for text source.
 ///
-/// Corresponds to the positional members of `GPUCompilationMessage` from the WebGPU specification,
-/// using utf8 instead of utf16 as reference encoding.
+/// Corresponds to the positional members of [`GPUCompilationMessage`][gcm] from
+/// the WebGPU specification, except that `offset` and `length` are in bytes
+/// (UTF-8 code units), instead of UTF-16 code units.
+///
+/// [gcm]: https://www.w3.org/TR/webgpu/#gpucompilationmessage
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct SourceLocation {
     /// 1-based line number.
@@ -220,6 +222,7 @@ impl<E> WithSpan<E> {
     }
 
     #[cfg(feature = "span")]
+    /// Return a [`SourceLocation`] for our first span, if we have one.
     pub fn location(&self, source: &str) -> Option<SourceLocation> {
         if self.spans.is_empty() {
             return None;
@@ -229,6 +232,7 @@ impl<E> WithSpan<E> {
     }
 
     #[cfg(not(feature = "span"))]
+    /// Return a [`SourceLocation`] for our first span, if we have one.
     pub fn location(&self, _source: &str) -> Option<SourceLocation> {
         None
     }