From 32ad73d8bd2f9852ea77a27ec4f0abe39e50a001 Mon Sep 17 00:00:00 2001
From: Saurabh Nanda <saurabh@vacationlabs.com>
Date: Mon, 23 Sep 2024 08:00:01 +0000
Subject: [PATCH] Exported Servant.Links.addQueryParam

---
 servant/servant.cabal        |  2 +-
 servant/src/Servant/Links.hs | 14 ++++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/servant/servant.cabal b/servant/servant.cabal
index cbb344067..47167c3ad 100644
--- a/servant/servant.cabal
+++ b/servant/servant.cabal
@@ -1,6 +1,6 @@
 cabal-version:      3.0
 name:               servant
-version:            0.20.2
+version:            0.20.3
 synopsis:           A family of combinators for defining webservices APIs
 category:           Servant, Web
 description:
diff --git a/servant/src/Servant/Links.hs b/servant/src/Servant/Links.hs
index 82c285d9d..2f60ef320 100644
--- a/servant/src/Servant/Links.hs
+++ b/servant/src/Servant/Links.hs
@@ -115,6 +115,8 @@ module Servant.Links (
   , linkSegments
   , linkQueryParams
   , linkFragment
+  , addQueryParam
+  , addSegment
 ) where
 
 import           Data.Kind
@@ -187,6 +189,10 @@ import           Web.HttpApiData
 -- | A safe link datatype.
 -- The only way of constructing a 'Link' is using 'safeLink', which means any
 -- 'Link' is guaranteed to be part of the mentioned API.
+--
+-- NOTE: If you are writing a custom 'HasLink' instance, and need to manipulate
+-- the 'Link' (adding query params or fragments, perhaps), please use the the
+-- 'addQueryParam' and 'addSegment' functions.
 data Link = Link
   { _segments    :: [Escaped]
   , _queryParams :: [Param]
@@ -232,10 +238,18 @@ data Param
 addSegment :: Escaped -> Link -> Link
 addSegment seg l = l { _segments = _segments l <> [seg] }
 
+-- | Add a 'Param' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addQueryParam :: Param -> Link -> Link
 addQueryParam qp l =
     l { _queryParams = _queryParams l <> [qp] }
 
+-- | Add a 'Fragment' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addFragment :: Fragment' -> Link -> Link
 addFragment fr l = l { _fragment = fr }