From 66b77b44340b84527ec11d021a352266d0ab2f68 Mon Sep 17 00:00:00 2001
From: Marcel Wilson <trenchrats@gmail.com>
Date: Thu, 8 Feb 2024 11:19:15 -0600
Subject: [PATCH] adding deprecation documentation for boolean positional
 keyword arguments

---
 docs/deprecations.rst | 80 +++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst        |  1 +
 tests/test_actions.py |  4 +--
 3 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 docs/deprecations.rst

diff --git a/docs/deprecations.rst b/docs/deprecations.rst
new file mode 100644
index 0000000..945cf83
--- /dev/null
+++ b/docs/deprecations.rst
@@ -0,0 +1,80 @@
+============
+Deprecations
+============
+
+This page documents
+the major deprecations
+in ScreenPy Selenium's life,
+and how to adjust your tests
+to keep them up to date.
+
+4.1.0 Deprecations
+==================
+
+Boolean Positional Arguments Deprecation
+----------------------------------------
+
+The following class constructors 
+have been marked deprecated 
+when using a positional boolean argument in the constructor. 
+Starting with version 5.0.0
+you will be required to provide keywords 
+for the following boolean arguments.
+
+:class:`~screenpy_selenium.actions.enter.Enter`
+
+Before::
+
+    the_actor.will(Enter("foo", True).into_the(PASSWORD))
+
+After::
+
+    the_actor.will(Enter("foo", mask=True).into_the(PASSWORD))
+
+
+:class:`~screenpy_selenium.actions.hold_down.HoldDown`
+
+Before::
+
+    the_actor.will(Chain(HoldDown(None, True))
+
+After::
+
+    the_actor.will(Chain(HoldDown(None, lmb=True))
+    the_actor.will(Chain(HoldDown(lmb=True))
+    
+
+:class:`~screenpy_selenium.actions.release.Release`
+
+Before::
+
+    the_actor.will(Release(None, True))
+
+After::
+
+    the_actor.will(Release(None, lmb=True))
+    the_actor.will(Release(lmb=True))
+
+
+:class:`~screenpy_selenium.questions.selected.Selected`
+
+Before::
+
+    the_actor.shall(See.the(Selected(TARGET, True), IsEmpty()))
+
+After::
+
+    the_actor.shall(See.the(Selected(TARGET, multi=True), IsEmpty()))
+
+
+:class:`~screenpy_selenium.questions.text.Text`
+
+Before::
+
+    the_actor.shall(See.the(Text(TARGET, True), IsEqual("foo"))
+
+After::
+
+    the_actor.shall(See.the(Text(TARGET, multi=True), IsEqual("foo")
+
+
diff --git a/docs/index.rst b/docs/index.rst
index 6c977c5..327b99e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -28,3 +28,4 @@ to :class:`~screenpy_selenium.abilities.BrowseTheWeb`!
    extended_api
    targets
    cookbook
+   deprecations
diff --git a/tests/test_actions.py b/tests/test_actions.py
index f58f183..9b325f9 100644
--- a/tests/test_actions.py
+++ b/tests/test_actions.py
@@ -635,7 +635,7 @@ def new_method(self) -> bool:
 
     def test_positional_arg_warns(self) -> None:
         with pytest.warns(DeprecationWarning):
-            HoldDown(Keys.LEFT_ALT, True)
+            HoldDown(None, True)
 
     def test_keyword_arg_does_not_warn(self) -> None:
         with warnings.catch_warnings():
@@ -913,7 +913,7 @@ def new_method(self) -> bool:
 
     def test_positional_arg_warns(self) -> None:
         with pytest.warns(DeprecationWarning):
-            Release(Keys.LEFT_ALT, True)
+            Release(None, True)
 
     def test_keyword_arg_does_not_warn(self) -> None:
         with warnings.catch_warnings():