From 6bb0c2a5c2513b38981a5751da56417a40f7620f Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Fri, 14 Oct 2022 06:33:38 -0700
Subject: [PATCH] Added documentation for some scancodes

---
 include/SDL_scancode.h       | 42 ++++++++++++++++++------------------
 src/events/scancodes_linux.h | 20 +++++++++++++++++
 2 files changed, 41 insertions(+), 21 deletions(-)

diff --git a/include/SDL_scancode.h b/include/SDL_scancode.h
index 6f40884ee..17e8fe2fd 100644
--- a/include/SDL_scancode.h
+++ b/include/SDL_scancode.h
@@ -225,16 +225,16 @@ typedef enum
     SDL_SCANCODE_F23 = 114,
     SDL_SCANCODE_F24 = 115,
     SDL_SCANCODE_EXECUTE = 116,
-    SDL_SCANCODE_HELP = 117,
-    SDL_SCANCODE_MENU = 118,
+    SDL_SCANCODE_HELP = 117,    /**< AL Integrated Help Center */
+    SDL_SCANCODE_MENU = 118,    /**< Menu (show menu) */
     SDL_SCANCODE_SELECT = 119,
-    SDL_SCANCODE_STOP = 120,
-    SDL_SCANCODE_AGAIN = 121,   /**< redo */
-    SDL_SCANCODE_UNDO = 122,
-    SDL_SCANCODE_CUT = 123,
-    SDL_SCANCODE_COPY = 124,
-    SDL_SCANCODE_PASTE = 125,
-    SDL_SCANCODE_FIND = 126,
+    SDL_SCANCODE_STOP = 120,    /**< AC Stop */
+    SDL_SCANCODE_AGAIN = 121,   /**< AC Redo/Repeat */
+    SDL_SCANCODE_UNDO = 122,    /**< AC Undo */
+    SDL_SCANCODE_CUT = 123,     /**< AC Cut */
+    SDL_SCANCODE_COPY = 124,    /**< AC Copy */
+    SDL_SCANCODE_PASTE = 125,   /**< AC Paste */
+    SDL_SCANCODE_FIND = 126,    /**< AC Find */
     SDL_SCANCODE_MUTE = 127,
     SDL_SCANCODE_VOLUMEUP = 128,
     SDL_SCANCODE_VOLUMEDOWN = 129,
@@ -265,9 +265,9 @@ typedef enum
     SDL_SCANCODE_LANG8 = 151, /**< reserved */
     SDL_SCANCODE_LANG9 = 152, /**< reserved */
 
-    SDL_SCANCODE_ALTERASE = 153, /**< Erase-Eaze */
+    SDL_SCANCODE_ALTERASE = 153,    /**< Erase-Eaze */
     SDL_SCANCODE_SYSREQ = 154,
-    SDL_SCANCODE_CANCEL = 155,
+    SDL_SCANCODE_CANCEL = 155,      /**< AC Cancel */
     SDL_SCANCODE_CLEAR = 156,
     SDL_SCANCODE_PRIOR = 157,
     SDL_SCANCODE_RETURN2 = 158,
@@ -359,17 +359,17 @@ typedef enum
     SDL_SCANCODE_AUDIOPLAY = 261,
     SDL_SCANCODE_AUDIOMUTE = 262,
     SDL_SCANCODE_MEDIASELECT = 263,
-    SDL_SCANCODE_WWW = 264,
+    SDL_SCANCODE_WWW = 264,             /**< AL Internet Browser */
     SDL_SCANCODE_MAIL = 265,
-    SDL_SCANCODE_CALCULATOR = 266,
+    SDL_SCANCODE_CALCULATOR = 266,      /**< AL Calculator */
     SDL_SCANCODE_COMPUTER = 267,
-    SDL_SCANCODE_AC_SEARCH = 268,
-    SDL_SCANCODE_AC_HOME = 269,
-    SDL_SCANCODE_AC_BACK = 270,
-    SDL_SCANCODE_AC_FORWARD = 271,
-    SDL_SCANCODE_AC_STOP = 272,
-    SDL_SCANCODE_AC_REFRESH = 273,
-    SDL_SCANCODE_AC_BOOKMARKS = 274,
+    SDL_SCANCODE_AC_SEARCH = 268,       /**< AC Search */
+    SDL_SCANCODE_AC_HOME = 269,         /**< AC Home */
+    SDL_SCANCODE_AC_BACK = 270,         /**< AC Back */
+    SDL_SCANCODE_AC_FORWARD = 271,      /**< AC Forward */
+    SDL_SCANCODE_AC_STOP = 272,         /**< AC Stop */
+    SDL_SCANCODE_AC_REFRESH = 273,      /**< AC Refresh */
+    SDL_SCANCODE_AC_BOOKMARKS = 274,    /**< AC Bookmarks */
 
     /* @} *//* Usage page 0x0C */
 
@@ -388,7 +388,7 @@ typedef enum
     SDL_SCANCODE_KBDILLUMDOWN = 279,
     SDL_SCANCODE_KBDILLUMUP = 280,
     SDL_SCANCODE_EJECT = 281,
-    SDL_SCANCODE_SLEEP = 282,
+    SDL_SCANCODE_SLEEP = 282,           /**< SC System Sleep */
 
     SDL_SCANCODE_APP1 = 283,
     SDL_SCANCODE_APP2 = 284,
diff --git a/src/events/scancodes_linux.h b/src/events/scancodes_linux.h
index 020f76ba9..325737746 100644
--- a/src/events/scancodes_linux.h
+++ b/src/events/scancodes_linux.h
@@ -825,6 +825,26 @@ fgrep SDL_SCANCODE scancodes_linux.h | while read line; do
 done
 #endif /* end script */
 
+#if 0 /* A shell script to get comments from the Linux header for these keys */
+#!/bin/bash
+
+function get_comment
+{   
+    name=$(echo "$1" | awk '{print $7}')
+    if [ "$name" != "" ]; then
+        egrep "$name\s" /usr/include/linux/input-event-codes.h | fgrep "/*" | sed 's,[^/]*/,/,'
+    fi
+}
+
+fgrep SDL_SCANCODE scancodes_linux.h | while read line; do
+    comment=$(get_comment "$line")
+    if [ "$comment" != "" ]; then
+        echo "    $line $comment"
+    fi
+done
+#endif /* end script */
+
+
 /* *INDENT-ON* */ /* clang-format on */
 
 /* vi: set ts=4 sw=4 expandtab: */