From dcaf9396984862d6daac6527c242d30570fa4110 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Tue, 7 Nov 2023 09:04:32 +0800
Subject: [PATCH] Add documentation for toga.Key.

---
 changes/2199.doc.rst         |  1 +
 core/src/toga/keys.py        |  6 +++++-
 docs/reference/api/index.rst |  2 ++
 docs/reference/api/keys.rst  | 41 ++++++++++++++++++++++++++++++++++++
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 changes/2199.doc.rst
 create mode 100644 docs/reference/api/keys.rst

diff --git a/changes/2199.doc.rst b/changes/2199.doc.rst
new file mode 100644
index 0000000000..4ee080ce2d
--- /dev/null
+++ b/changes/2199.doc.rst
@@ -0,0 +1 @@
+Documentation for ``toga.Key`` was added.
diff --git a/core/src/toga/keys.py b/core/src/toga/keys.py
index 17009c42d4..6e78728eb8 100644
--- a/core/src/toga/keys.py
+++ b/core/src/toga/keys.py
@@ -2,6 +2,9 @@
 
 
 class Key(Enum):
+    """An enumeration providing a symbolic representation for the characters on
+    a keyboard."""
+
     A = "a"
     B = "b"
     C = "c"
@@ -144,7 +147,8 @@ class Key(Enum):
     NUMPAD_MULTIPLY = "numpad:*"
     NUMPAD_PLUS = "numpad:+"
 
-    def is_printable(self):
+    def is_printable(self) -> bool:
+        """Does pressing the key result in a printable character?"""
         return not (self.value.startswith("<") and self.value.endswith(">"))
 
     def __add__(self, other):
diff --git a/docs/reference/api/index.rst b/docs/reference/api/index.rst
index 0165206842..3b46b6e653 100644
--- a/docs/reference/api/index.rst
+++ b/docs/reference/api/index.rst
@@ -96,6 +96,7 @@ Other
  Component                                      Description
 ============================================== ========================================================================
  :doc:`Constants </reference/api/constants>`    Symbolic constants used by various APIs.
+ :doc:`Keys </reference/api/keys>`              Symbolic representation of keys used for keyboard shortcuts.
 ============================================== ========================================================================
 
 .. toctree::
@@ -109,3 +110,4 @@ Other
    resources/index
    widgets/index
    constants
+   keys
diff --git a/docs/reference/api/keys.rst b/docs/reference/api/keys.rst
new file mode 100644
index 0000000000..31e1f175a4
--- /dev/null
+++ b/docs/reference/api/keys.rst
@@ -0,0 +1,41 @@
+Keys
+====
+
+A symbolic representation of keys used for keyboard shortcuts.
+
+Most keys have a constant that matches the text on the key, or the name of the
+key if the text on the key isn't a legal Python identifier.
+
+However, due to differences between platforms, there's no representation of
+"modifier" keys like Control, Command, Option, or the Windows Key. Instead, Toga
+provides three generic modifier constants, and maps those to the modifier keys,
+matching the precedence with which they are used on the underlying platforms:
+
+========== ============== ============== ==================
+ Platform   :any:`MOD_1`   :any:`MOD_2`   :any:`MOD_3`
+========== ============== ============== ==================
+ Linux      Control        Alt            Tux/Windows/Meta
+ macOS      Command (⌘)    Option         Control (^)
+ Windows    Control        Alt            Not supported
+========== ============== ============== ==================
+
+Key combinations can be expressed by combining multiple ``Key`` values with the
+``+`` operator.
+
+.. code-block:: python
+
+    from toga import Key
+
+    just_an_a = Key.A
+    shift_a = Key.SHIFT + Key.A
+    # Windows/Linux - Control-Shift-A:
+    # macOS - Command-Shift-A:
+    modified_shift_a = Key.MOD_1 + Key.SHIFT + Key.A
+
+The order of addition is not significant. ``Key.SHIFT + Key.A`` and ``Key.A +
+Key.SHIFT`` will produce the same key representation.
+
+Reference
+---------
+
+.. autoclass:: toga.Key