fixed

commit 4730a3b70f0dfa70d726d54d46d2f764a315df0e
parent 6ad24b1ba0161bbf1b99b8e6bbc30b734cb02fdf
Author: Jared Tobin <jared@jtobin.io>
Date:   Sat,  1 Aug 2026 14:08:42 -0230

lib: fix inverted select haddocks

The select wrappers documented "return a if c is truthy, otherwise
return b", but the implementations (and their doctests, and all
internal call sites) return the second argument when the choice is
truthy. Correct the prose, and state the ordering explicitly on the
Data.Choice selection primitives.

Diffstat:
M
lib/Data/Choice.hs
 | 
9
+++++++++
M
lib/Data/Word/Limb.hs
 | 
2
+-
M
lib/Data/Word/Wide.hs
 | 
2
+-
M
lib/Data/Word/Wider.hs
 | 
2
+-
M
lib/Numeric/Montgomery/Secp256k1/Curve.hs
 | 
2
+-
M
lib/Numeric/Montgomery/Secp256k1/Scalar.hs
 | 
2
+-

6 files changed, 14 insertions(+), 5 deletions(-)
diff --git a/lib/Data/Choice.hs b/lib/Data/Choice.hs
@@ -305,6 +305,9 @@ eq c0 c1 = not (ne c0 c1)
 
 -- | Select an unboxed word without branching, given a 'Choice'.
 --
+--   Returns the second word if the 'Choice' is truthy, and the first
+--   otherwise.
+--
 --   >>> let w = C.select_word# 0## 1## (C.true# ()) in GHC.Word.W# w
 --   1
 select_word# :: Word# -> Word# -> Choice -> Word#
@@ -312,6 +315,9 @@ select_word# a b (Choice c) = Exts.xor# a (Exts.and# c (Exts.xor# a b))
 {-# INLINE select_word# #-}
 
 -- | Select an unboxed two-limb word without branching, given a 'Choice'.
+--
+--   Returns the second word if the 'Choice' is truthy, and the first
+--   otherwise.
 select_wide#
   :: Limb2
   -> Limb2
@@ -323,6 +329,9 @@ select_wide# a b (Choice w) =
 {-# INLINE select_wide# #-}
 
 -- | Select an unboxed four-limb word without branching, given a 'Choice'.
+--
+--   Returns the second word if the 'Choice' is truthy, and the first
+--   otherwise.
 select_wider#
   :: Limb4
   -> Limb4
diff --git a/lib/Data/Word/Limb.hs b/lib/Data/Word/Limb.hs
@@ -143,7 +143,7 @@ gt# (Limb a) (Limb b) = C.from_word_gt# a b
 
 -- constant-time selection ----------------------------------------------------
 
--- | Return a if c is truthy, otherwise return b.
+-- | Return b if c is truthy, otherwise return a.
 select#
   :: Limb     -- ^ a
   -> Limb     -- ^ b
diff --git a/lib/Data/Word/Wide.hs b/lib/Data/Word/Wide.hs
@@ -159,7 +159,7 @@ eq_vartime (Wide (# a0, b0 #)) (Wide (# a1, b1 #)) =
 
 -- constant-time selection-----------------------------------------------------
 
--- | Return a if c is truthy, otherwise return b.
+-- | Return b if c is truthy, otherwise return a.
 --
 --   >>> import qualified Data.Choice as C
 --   >>> select 0 1 (C.true# ())
diff --git a/lib/Data/Word/Wider.hs b/lib/Data/Word/Wider.hs
@@ -319,7 +319,7 @@ select# (L4 a0 a1 a2 a3) (L4 b0 b1 b2 b3) c =
   in  L4 w0 w1 w2 w3
 {-# INLINE select# #-}
 
--- | Return a if c is truthy, otherwise return b.
+-- | Return b if c is truthy, otherwise return a.
 --
 --   >>> import qualified Data.Choice as C
 --   >>> select 0 1 (C.true# ())
diff --git a/lib/Numeric/Montgomery/Secp256k1/Curve.hs b/lib/Numeric/Montgomery/Secp256k1/Curve.hs
@@ -1354,7 +1354,7 @@ select#
 select# = WW.select#
 {-# INLINE select# #-}
 
--- | Return a if c is truthy, otherwise return b.
+-- | Return b if c is truthy, otherwise return a.
 --
 --   >>> import qualified Data.Choice as C
 --   >>> select 0 1 (C.true# ())
diff --git a/lib/Numeric/Montgomery/Secp256k1/Scalar.hs b/lib/Numeric/Montgomery/Secp256k1/Scalar.hs
@@ -856,7 +856,7 @@ select#
 select# = WW.select#
 {-# INLINE select# #-}
 
--- | Return a if c is truthy, otherwise return b.
+-- | Return b if c is truthy, otherwise return a.
 --
 --   >>> import qualified Data.Choice as C
 --   >>> select 0 1 (C.true# ())