From fdef224a0691df475337ddfc1693da32148cfba8 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sat, 23 Dec 2023 18:49:17 +0000
Subject: [PATCH] docs: document internal Path fields

---
 actix-router/src/path.rs | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/actix-router/src/path.rs b/actix-router/src/path.rs
index dc4150ddc..467420cd3 100644
--- a/actix-router/src/path.rs
+++ b/actix-router/src/path.rs
@@ -3,7 +3,7 @@ use std::{
     ops::{DerefMut, Index},
 };
 
-use serde::de;
+use serde::{de, Deserialize};
 
 use crate::{de::PathDeserializer, Resource, ResourcePath};
 
@@ -24,8 +24,13 @@ impl Default for PathItem {
 /// If resource path contains variable patterns, `Path` stores them.
 #[derive(Debug, Clone, Default)]
 pub struct Path<T> {
+    /// Full path representation.
     path: T,
+
+    /// Number of characters in `path` that have been processed into `segments`.
     pub(crate) skip: u16,
+
+    /// List of processed dynamic segments; name->value pairs.
     pub(crate) segments: Vec<(Cow<'static, str>, PathItem)>,
 }
 
@@ -83,8 +88,8 @@ impl<T: ResourcePath> Path<T> {
     /// Set new path.
     #[inline]
     pub fn set(&mut self, path: T) {
-        self.skip = 0;
         self.path = path;
+        self.skip = 0;
         self.segments.clear();
     }
 
@@ -103,7 +108,7 @@ impl<T: ResourcePath> Path<T> {
 
     pub(crate) fn add(&mut self, name: impl Into<Cow<'static, str>>, value: PathItem) {
         match value {
-            PathItem::Static(s) => self.segments.push((name.into(), PathItem::Static(s))),
+            PathItem::Static(seg) => self.segments.push((name.into(), PathItem::Static(seg))),
             PathItem::Segment(begin, end) => self.segments.push((
                 name.into(),
                 PathItem::Segment(self.skip + begin, self.skip + end),
@@ -168,9 +173,13 @@ impl<T: ResourcePath> Path<T> {
         }
     }
 
-    /// Try to deserialize matching parameters to a specified type `U`
-    pub fn load<'de, U: serde::Deserialize<'de>>(&'de self) -> Result<U, de::value::Error> {
-        de::Deserialize::deserialize(PathDeserializer::new(self))
+    /// Deserializes matching parameters to a specified type `U`.
+    ///
+    /// # Errors
+    ///
+    /// Returns error when dynamic path segments cannot be deserialized into a `U` type.
+    pub fn load<'de, U: Deserialize<'de>>(&'de self) -> Result<U, de::value::Error> {
+        Deserialize::deserialize(PathDeserializer::new(self))
     }
 }