From 02684e3e981b4842bf59bc330f8d34cd79ceb61a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kha=C3=AFs=20COLIN=20=28aider=29?= <khais.colin@gmail.com>
Date: Thu, 5 Jun 2025 10:10:25 +0200
Subject: [PATCH] docs: Add comprehensive documentation and doctests to
 Location struct

---
 src/tokens/location.rs | 58 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/tokens/location.rs b/src/tokens/location.rs
index ff11c9d..5cbbae7 100644
--- a/src/tokens/location.rs
+++ b/src/tokens/location.rs
@@ -1,12 +1,41 @@
-/// Represents a location in the source input
+/// Represents a location in source code for error reporting and debugging.
+///
+/// Stores information about where a token or error occurred in the source input,
+/// including the file name, UTF-8 char offset position, and length of the relevant span.
+///
+/// # Examples
+///
+/// ```
+/// use osdb::tokens::location::Location;
+///
+/// // Create a location for a token starting at UTF-8 char 10 spanning 5 UTF-8 chars
+/// let loc = Location::new("main.rs".into(), 10, 5);
+/// assert_eq!(loc.file, "main.rs");
+/// assert_eq!(loc.offset, 10);
+/// assert_eq!(loc.length, 5);
+/// ```
 #[derive(Debug, Eq, PartialEq, Clone)]
 pub struct Location {
+    /// The source file path where this location occurs
     pub file: String,
+    /// The starting UTF-8 char offset in the source file (0-based)
     pub offset: usize,
+    /// The number of UTF-8 chars this location spans
     pub length: usize,
 }
 
 impl From<&Location> for std::ops::Range<usize> {
+    /// Converts a Location to a UTF-8 char range for slicing source input.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use osdb::tokens::location::Location;
+    /// let loc = Location::new("test.sql".into(), 5, 3);
+    /// let range: std::ops::Range<usize> = (&loc).into();
+    /// assert_eq!(range.start, 5);
+    /// assert_eq!(range.end, 8);
+    /// ```
     fn from(val: &Location) -> Self {
         std::ops::Range {
             start: val.offset,
@@ -16,12 +45,39 @@ impl From<&Location> for std::ops::Range<usize> {
 }
 
 impl Default for Location {
+    /// Creates a default Location with unknown file and zero positions.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use osdb::tokens::location::Location;
+    /// let loc = Location::default();
+    /// assert_eq!(loc.file, "<unknown>");
+    /// assert_eq!(loc.offset, 0);
+    /// assert_eq!(loc.length, 0);
+    /// ```
     fn default() -> Self {
         Self::new(String::from("<unknown>"), 0, 0)
     }
 }
 
 impl Location {
+    /// Constructs a new Location with specified parameters.
+    ///
+    /// # Arguments
+    ///
+    /// * `file` - Source file path
+    /// * `offset` - Starting UTF-8 char position in the file
+    /// * `length` - Number of UTF-8 chars spanned by this location
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use osdb::tokens::location::Location;
+    /// let loc = Location::new("script.sql".into(), 20, 4);
+    /// assert_eq!(loc.offset, 20);
+    /// assert_eq!(loc.length, 4);
+    /// ```
     pub fn new(file: String, offset: usize, length: usize) -> Self {
         Self {
             file,