docs(style): add guideline for fixing compiler error on switch statement

Problem: Certain compilers (primarily GCC) do not recognize an exhaustive enum switch statement as being exhaustive. This manifests in the form of compiler errors in exhaustive switch statements where each case has a return statement but there isn't a catch-all return statements. These compiler errors are spurious in the context of the Neovim codebase. So #25533 added the `UNREACHABLE` macro to denote apart of the code that's unreachable, which was used after every such switch statement to tell the compiler to treat the switch statement as exhaustive. However, the macro is mentioned nowhere in the style guide,and new contributors would not have any natural way of learning about it as it stands now. This would lead to confusion when they inevitably encounter one of these compiler errors.

Solution: Add a style guideline which shows how to use the `UNREACHABLE` macro to fix these compiler errors.

1 files changed, 19 insertions, 0 deletions

diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt
index 0bc27ced15..d6c465ef91 100644
--- a/runtime/doc/dev_style.txt
+++ b/runtime/doc/dev_style.txt
@@ -886,6 +886,25 @@ You should use: >c
     case F:
       ...
 
+Certain compilers do not recognize an exhaustive enum switch statement as
+exhaustive, which causes compiler warnings when there is a return statement in
+every case of a switch statement, but no catch-all return statement. To fix
+these spurious errors, you are advised to use `UNREACHABLE` after the switch
+statement to explicitly tell the compiler that the switch statement always
+returns and any code after it is unreachable. For example: >c
+
+    enum { A, B, C } var;
+    ...
+    switch (var) {
+      case A:
+        return 1;
+      case B:
+        return 2;
+      case C:
+        return 3;
+    }
+    UNREACHABLE;
+
 Return Values ~
 
 Do not needlessly surround the `return` expression with parentheses.