From 6c91e0cbcc35708d6ecffb961aac1ece84900979 Mon Sep 17 00:00:00 2001
From: krzysdz <krzysdz@users.noreply.github.com>
Date: Sun, 2 Nov 2025 00:20:57 +0100
Subject: [PATCH] docs: clarify req.params type and usage with regular
 expressions

Fixes #2100
---
 _includes/api/en/4x/req-params.md | 4 +++-
 _includes/api/en/5x/req-params.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/_includes/api/en/4x/req-params.md b/_includes/api/en/4x/req-params.md
index 5c08065e08..a92d640508 100644
--- a/_includes/api/en/4x/req-params.md
+++ b/_includes/api/en/4x/req-params.md
@@ -8,7 +8,7 @@ console.dir(req.params.name)
 // => 'tj'
 ```
 
-When you use a regular expression for the route definition, capture groups are provided in the array using `req.params[n]`, where `n` is the n<sup>th</sup> capture group. This rule is applied to unnamed wild card matches with string routes such as `/file/*`:
+When you use a regular expression for the route definition, capture groups are provided as integer keys using `req.params[n]`, where `n` is the n<sup>th</sup> capture group. This rule is applied to unnamed wild card matches with string routes such as `/file/*`:
 
 ```js
 // GET /file/javascripts/jquery.js
@@ -16,6 +16,8 @@ console.dir(req.params[0])
 // => 'javascripts/jquery.js'
 ```
 
+Named capturing groups in regular expressions behave like named route parameters. For example the group from `/^\/file\/(?<path>.*)$/` expression is available as `req.params.path`.
+
 If you need to make changes to a key in `req.params`, use the [app.param](/{{ page.lang }}/4x/api.html#app.param) handler. Changes are applicable only to [parameters](/{{ page.lang }}/guide/routing.html#route-parameters) already defined in the route path.
 
 Any changes made to the `req.params` object in a middleware or route handler will be reset.
diff --git a/_includes/api/en/5x/req-params.md b/_includes/api/en/5x/req-params.md
index 2f48c828d4..720f5ee7f1 100644
--- a/_includes/api/en/5x/req-params.md
+++ b/_includes/api/en/5x/req-params.md
@@ -8,7 +8,7 @@ console.dir(req.params.name)
 // => "tj"
 ```
 
-When you use a regular expression for the route definition, capture groups are provided in the array using `req.params[n]`, where `n` is the n<sup>th</sup> capture group.
+When you use a regular expression for the route definition, capture groups are provided as integer keys using `req.params[n]`, where `n` is the n<sup>th</sup> capture group.
 
 ```js
 app.use(/^\/file\/(.*)$/, (req, res) => {
@@ -18,6 +18,8 @@ app.use(/^\/file\/(.*)$/, (req, res) => {
 })
 ```
 
+Named capturing groups in regular expressions behave like named route parameters. For example the group from `/^\/file\/(?<path>.*)$/` expression is available as `req.params.path`.
+
 If you need to make changes to a key in `req.params`, use the [app.param](/{{ page.lang }}/5x/api.html#app.param) handler. Changes are applicable only to [parameters](/{{ page.lang }}/guide/routing.html#route-parameters) already defined in the route path.
 
 Any changes made to the `req.params` object in a middleware or route handler will be reset.