Add #[doc(alias = ...)] attributes

For certain keys and codes where it makes sense, including those we
already have alternatives for when parsing.

Author: madsmtm

convert.py

@@ -46,49 +46,60 @@ def parse(text):
 
             comment = re.sub(r"[ \t][ \t]+", "\n", typical_usage.decode_contents())
 
-            display.append([name, comment, deprecated, []])
+            display.append([name, comment, deprecated, [], []])
     return display
 
 
 def emit_enum_entries(display, file):
-    for [key, doc_comment, deprecated, alternatives] in display:
+    for [key, doc_comment, deprecated, alternatives, aliases] in display:
         for line in doc_comment.split('\n'):
             line = line.strip()
             if len(line) == 0:
                 continue
             print(f"    /// {line}", file=file)
         if deprecated:
             print("    #[deprecated = \"marked as legacy in the spec, use Meta instead\"]", file=file)
+        for alias in aliases:
+            print(f"    #[doc(alias = \"{alias}\")]", file=file)
         print(f"    {key},", file=file)
 
 
 def print_display_entries(display, file):
-    for [key, doc_comment, deprecated, alternatives] in display:
+    for [key, doc_comment, deprecated, alternatives, aliases] in display:
         print("            {0} => f.write_str(\"{0}\"),".format(
             key), file=file)
 
 
 def print_from_str_entries(display, file):
-    for [key, doc_comment, deprecated, alternatives] in display:
+    for [key, doc_comment, deprecated, alternatives, aliases] in display:
         print("            \"{0}\"".format(key), file=file, end='')
         for alternative in alternatives:
             print(" | \"{0}\"".format(alternative), file=file, end='')
         print(" => Ok({0}),".format(key), file=file)
 
 
 def add_comment_to(display, key, comment):
-    for (i, [found_key, doc_comment, deprecated, alternatives]) in enumerate(display):
+    for (i, [found_key, doc_comment, deprecated, alternatives, aliases]) in enumerate(display):
         if found_key != key:
             continue
         doc_comment = doc_comment + "\n" + comment
-        display[i] = [found_key, doc_comment, deprecated, alternatives]
+        display[i] = [found_key, doc_comment, deprecated, alternatives, aliases]
+
+
+def add_alias_for(display, key, alias):
+    for [found_key, doc_comment, deprecated, alternatives, aliases] in display:
+        if found_key != key:
+            continue
+        aliases.append(alias)
 
 
 def add_alternative_for(display, key, alternative):
-    for [found_key, doc_comment, deprecated, alternatives] in display:
+    for [found_key, doc_comment, deprecated, alternatives, aliases] in display:
         if found_key != key:
             continue
         alternatives.append(alternative)
+        # Alternatives are also listed as aliases
+        aliases.append(alternative)
 
 
 def convert_key(text, file):
@@ -118,11 +129,15 @@ def convert_key(text, file):
             'F{}'.format(i),
             'The F{0} key, a general purpose function key, as index {0}.'.format(i),
             False,
-            []
+            [],
+            [],
         ])
 
     add_comment_to(display, 'Meta', 'In Linux (XKB) terminology, this is often referred to as "Super".')
 
+    add_alias_for(display, 'Meta', 'Super')
+    add_alias_for(display, 'Enter', 'Return')
+
     emit_enum_entries(display, file)
     print("}", file=file)
 
@@ -196,7 +211,8 @@ def convert_code(text, file):
             'F{}'.format(i),
             '<kbd>F{}</kbd>'.format(i),
             False,
-            []
+            [],
+            [],
         ])
 
     chromium_key_codes = [
@@ -228,14 +244,22 @@ def convert_code(text, file):
             chromium_only,
             'Non-standard code value supported by Chromium.',
             False,
-            []
+            [],
+            [],
         ])
 
     add_comment_to(display, 'Backquote', 'This is also called a backtick or grave.')
     add_comment_to(display, 'Quote', 'This is also called an apostrophe.')
     add_comment_to(display, 'MetaLeft', 'In Linux (XKB) terminology, this is often referred to as the left "Super".')
     add_comment_to(display, 'MetaRight', 'In Linux (XKB) terminology, this is often referred to as the right "Super".')
 
+    add_alias_for(display, 'Backquote', 'Backtick')
+    add_alias_for(display, 'Backquote', 'Grave')
+    add_alias_for(display, 'Quote', 'Apostrophe')
+    add_alias_for(display, 'MetaLeft', 'SuperLeft')
+    add_alias_for(display, 'MetaRight', 'SuperRight')
+    add_alias_for(display, 'Enter', 'Return')
+
     add_alternative_for(display, 'MetaLeft', 'OSLeft')
     add_alternative_for(display, 'MetaRight', 'OSRight')
     add_alternative_for(display, 'AudioVolumeDown', 'VolumeDown')

src/code.rs

@@ -23,6 +23,8 @@ use std::error::Error;
 pub enum Code {
     /// <kbd>`~</kbd> on a US keyboard. This is the <kbd>半角/全角/漢字</kbd> (<span class="unicode">hankaku/zenkaku/kanji</span>) key on Japanese keyboards
     /// This is also called a backtick or grave.
+    #[doc(alias = "Backtick")]
+    #[doc(alias = "Grave")]
     Backquote,
     /// Used for both the US <kbd>\|</kbd> (on the 101-key layout) and also for the key
     /// located between the <kbd>"</kbd> and <kbd>Enter</kbd> keys on row C of the 102-,
@@ -131,6 +133,7 @@ pub enum Code {
     Period,
     /// <kbd>'"</kbd> on a US keyboard.
     /// This is also called an apostrophe.
+    #[doc(alias = "Apostrophe")]
     Quote,
     /// <kbd>;:</kbd> on a US keyboard.
     Semicolon,
@@ -153,12 +156,17 @@ pub enum Code {
     /// <kbd>Control</kbd> or <kbd>⌃</kbd>
     ControlRight,
     /// <kbd>Enter</kbd> or <kbd>↵</kbd>. Labelled <kbd>Return</kbd> on Apple keyboards.
+    #[doc(alias = "Return")]
     Enter,
     /// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd> or other OS symbol key.
     /// In Linux (XKB) terminology, this is often referred to as the left "Super".
+    #[doc(alias = "SuperLeft")]
+    #[doc(alias = "OSLeft")]
     MetaLeft,
     /// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd> or other OS symbol key.
     /// In Linux (XKB) terminology, this is often referred to as the right "Super".
+    #[doc(alias = "SuperRight")]
+    #[doc(alias = "OSRight")]
     MetaRight,
     /// <kbd>Shift</kbd> or <kbd>⇧</kbd>
     ShiftLeft,
@@ -313,6 +321,7 @@ pub enum Code {
     LaunchApp2,
     LaunchMail,
     MediaPlayPause,
+    #[doc(alias = "LaunchMediaPlayer")]
     MediaSelect,
     MediaStop,
     MediaTrackNext,
@@ -321,8 +330,11 @@ pub enum Code {
     /// replacing the <kbd>Eject</kbd> key.
     Power,
     Sleep,
+    #[doc(alias = "VolumeDown")]
     AudioVolumeDown,
+    #[doc(alias = "VolumeMute")]
     AudioVolumeMute,
+    #[doc(alias = "VolumeUp")]
     AudioVolumeUp,
     WakeUp,
     #[deprecated = "marked as legacy in the spec, use Meta instead"]

src/named_key.rs

@@ -42,6 +42,7 @@ pub enum NamedKey {
     /// The <kbd>Meta</kbd> key, to enable meta modifier function for interpreting concurrent or subsequent keyboard input.
     /// This key value is used for the <q>Windows Logo</q> key and the Apple <kbd>Command</kbd> or <kbd>⌘</kbd> key.
     /// In Linux (XKB) terminology, this is often referred to as "Super".
+    #[doc(alias = "Super")]
     Meta,
     /// The <kbd>NumLock</kbd> or Number Lock key, to toggle numpad mode function for interpreting subsequent keyboard input.
     NumLock,
@@ -60,6 +61,7 @@ pub enum NamedKey {
     #[deprecated = "marked as legacy in the spec, use Meta instead"]
     Super,
     /// The <kbd>Enter</kbd> or <kbd>↵</kbd> key, to activate current selection or accept current input.<br/> This key value is also used for the <kbd>Return</kbd> (Macintosh numpad) key.<br/> This key value is also used for the Android <code class="android">KEYCODE_DPAD_CENTER</code>.
+    #[doc(alias = "Return")]
     Enter,
     /// The Horizontal Tabulation <kbd>Tab</kbd> key.
     Tab,