Add documentation for toga.Key.

changes/2199.doc.rst

@@ -0,0 +1 @@
+Documentation for ``toga.Key`` was added.

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):

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

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            Windows
+ macOS      Command (⌘)    Option         Control (^)
+ Windows    Control        Alt            Tux/Windows/Meta
+========== ============== ============== ==================
+
+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