glfw: document why unreachable is valid

glfw/src/Cursor.zig

@@ -69,6 +69,7 @@ pub inline fn create(image: Image, xhot: i32, yhot: i32) error{PlatformError}!Cu
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwCreateCursor` returns `null` only for errors
     unreachable;
 }
 
@@ -90,6 +91,7 @@ pub inline fn createStandard(shape: Shape) error{PlatformError}!Cursor {
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwCreateStandardCursor` returns `null` only for errors
     unreachable;
 }
 

glfw/src/Monitor.zig

@@ -169,6 +169,7 @@ pub inline fn getName(self: Monitor) [*:0]const u8 {
         Error.NotInitialized => unreachable,
         else => unreachable,
     };
+    // `glfwGetMonitorName` returns `null` only for errors
     unreachable;
 }
 
@@ -247,6 +248,7 @@ pub inline fn getVideoModes(self: Monitor, allocator: mem.Allocator) (mem.Alloca
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwGetVideoModes` returns `null` only for errors
     unreachable;
 }
 
@@ -269,6 +271,7 @@ pub inline fn getVideoMode(self: Monitor) error{PlatformError}!VideoMode {
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwGetVideoMode` returns `null` only for errors
     unreachable;
 }
 
@@ -330,6 +333,7 @@ pub inline fn getGammaRamp(self: Monitor) error{PlatformError}!GammaRamp {
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwGetGammaRamp` returns `null` only for errors
     unreachable;
 }
 

glfw/src/Window.zig

@@ -444,7 +444,7 @@ pub inline fn create(
 
         else => unreachable,
     };
-
+    // `glfwCreateWindow` returns `null` only for errors
     unreachable;
 }
 
@@ -1304,6 +1304,7 @@ pub inline fn getAttrib(self: Window, attrib: Attrib) error{PlatformError}!i32 {
         Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // this is not unreachable as `0` is a valid value
     return v;
 }
 

glfw/src/clipboard.zig

@@ -54,6 +54,7 @@ pub inline fn getClipboardString() error{ FormatUnavailable, PlatformError }![:0
         Error.FormatUnavailable, Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwGetClipboardString` returns `null` only for errors
     unreachable;
 }
 

glfw/src/key.zig

@@ -250,6 +250,7 @@ pub const Key = enum(c_int) {
             Error.PlatformError => |e| e,
             else => unreachable,
         };
+        // `glfwGetKeyScancode` returns `-1` only for errors
         unreachable;
     }
 };

glfw/src/native.zig

@@ -72,6 +72,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWin32Adapter` returns `null` only for errors
             unreachable;
         }
 
@@ -90,6 +91,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWin32Monitor` returns `null` only for errors
             unreachable;
         }
 
@@ -114,6 +116,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWin32Window` returns `null` only for errors
             unreachable;
         }
 
@@ -138,6 +141,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetWGLContext` returns `null` only for errors
             unreachable;
         }
 
@@ -154,6 +158,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetCocoaMonitor` returns `kCGNullDirectDisplay` only for errors
             unreachable;
         }
 
@@ -200,6 +205,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetX11Display` returns `null` only for errors
             unreachable;
         }
 
@@ -216,6 +222,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetX11Adapter` returns `0` only for errors
             unreachable;
         }
 
@@ -232,6 +239,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetX11Monitor` returns `0` only for errors
             unreachable;
         }
 
@@ -248,6 +256,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetX11Window` returns `0` only for errors
             unreachable;
         }
 
@@ -285,6 +294,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.FormatUnavailable => |e| e,
                 else => unreachable,
             };
+            // `glfwGetX11SelectionString` returns `null` only for errors
             unreachable;
         }
 
@@ -301,6 +311,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetGLXContext` returns `null` only for errors
             unreachable;
         }
 
@@ -318,6 +329,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetGLXWindow` returns `0` only for errors
             unreachable;
         }
 
@@ -333,6 +345,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWaylandDisplay` returns `null` only for errors
             unreachable;
         }
 
@@ -348,6 +361,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWaylandMonitor` returns `null` only for errors
             unreachable;
         }
 
@@ -363,6 +377,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetWaylandWindow` returns `null` only for errors
             unreachable;
         }
 
@@ -379,6 +394,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NotInitialized => unreachable,
                 else => unreachable,
             };
+            // `glfwGetEGLDisplay` returns `EGL_NO_DISPLAY` only for errors
             unreachable;
         }
 
@@ -396,6 +412,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetEGLContext` returns `EGL_NO_CONTEXT` only for errors
             unreachable;
         }
 
@@ -413,6 +430,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetEGLSurface` returns `EGL_NO_SURFACE` only for errors
             unreachable;
         }
 
@@ -444,6 +462,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.PlatformError, Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetOSMesaColorBuffer` returns `GLFW_FALSE` only for errors
             unreachable;
         }
 
@@ -475,6 +494,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.PlatformError, Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetOSMesaDepthBuffer` returns `GLFW_FALSE` only for errors
             unreachable;
         }
 
@@ -491,6 +511,7 @@ pub fn Native(comptime options: BackendOptions) type {
                 Error.NoWindowContext => |e| e,
                 else => unreachable,
             };
+            // `glfwGetOSMesaContext` returns `null` only for errors
             unreachable;
         }
     };

glfw/src/time.zig

@@ -35,6 +35,7 @@ pub inline fn getTime() f64 {
         Error.NotInitialized => unreachable,
         else => unreachable,
     };
+    // `glfwGetTime` returns `0` only for errors
     unreachable;
 }
 
@@ -94,6 +95,7 @@ pub inline fn getTimerValue() u64 {
         Error.NotInitialized => unreachable,
         else => unreachable,
     };
+    // `glfwGetTimerValue` returns `0` only for errors
     unreachable;
 }
 
@@ -114,6 +116,7 @@ pub inline fn getTimerFrequency() u64 {
         Error.NotInitialized => unreachable,
         else => unreachable,
     };
+    // `glfwGetTimerFrequency` returns `0` only for errors
     unreachable;
 }
 

glfw/src/vulkan.zig

@@ -68,6 +68,7 @@ pub inline fn getRequiredInstanceExtensions() error{APIUnavailable}![][*:0]const
         Error.APIUnavailable => |e| e,
         else => unreachable,
     };
+    // `glfwGetRequiredInstanceExtensions` returns `null` only for errors
     unreachable;
 }
 
@@ -227,6 +228,7 @@ pub inline fn createWindowSurface(vk_instance: anytype, window: Window, vk_alloc
         Error.APIUnavailable, Error.PlatformError => |e| e,
         else => unreachable,
     };
+    // `glfwCreateWindowSurface` returns `!VK_SUCCESS` only for errors
     unreachable;
 }