From 6d5ddcde49fbf73789cde8c7e7d3b6b61c983d15 Mon Sep 17 00:00:00 2001
From: Zoom <ZoomRmc@users.noreply.github.com>
Date: Fri, 27 Jun 2025 12:49:02 +0400
Subject: [PATCH] [docs]: warning for `long`, `culong` being OS-dependent
 (#25012)

Docs are routinely compiled on a different OS so often don't reflect
reality of CT-conditionals.

I bet there's a few of other places like this in the stdlib.

(cherry picked from commit 6bdb069a6651e419b2d808f488051322cd05d753)
---
 lib/system/ctypes.nim | 45 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 7 deletions(-)

diff --git a/lib/system/ctypes.nim b/lib/system/ctypes.nim
index b788274bd7..5cc092d9c5 100644
--- a/lib/system/ctypes.nim
+++ b/lib/system/ctypes.nim
@@ -17,18 +17,50 @@ type
     ## supports. Currently this is `uint64`, but it is platform-dependent
     ## in general.
 
-when defined(windows):
+when defined(nimdoc):
+  type
+    # "Opaque" types defined only in the `nimdoc` branch to not show in error
+    # messages in regular code with `clong` and `culong` resolving to base types
+    ClongImpl = (when defined(windows): int32 else: int)
+    CulongImpl = (when defined(windows): uint32 else: uint)
+    clong* = ClongImpl
+      ## Represents the *C* `long` type, used for interoperability.
+      ##
+      ## Its purpose is to match the *C* `long` for the target
+      ## platform's Application Binary Interface (ABI).
+      ##
+      ## Typically, the compiler resolves it to one of the following Nim types
+      ## based on the target:
+      ## - `int32 <system.html#int32>`_ on Windows using MSVC or MinGW compilers.
+      ## - `int <system.html#int>`_ on Linux, macOS and other platforms that use the
+      ##    LP64 or ILP32 `data models
+      ## <https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models>`_.
+      ##
+      ## .. warning:: The underlying Nim type is an implementation detail and
+      ##    should not be relied upon.
+    culong* = CulongImpl
+      ## Represents the *C* `unsigned long` type, used for interoperability.
+      ##
+      ## Its purpose is to match the *C* `unsigned long` for the target
+      ## platform's Application Binary Interface (ABI).
+      ##
+      ## Typically, the compiler resolves it to one of the following Nim types
+      ## based on the target:
+      ## - `uint32 <system.html#uint32>`_ on Windows using MSVC or MinGW compilers.
+      ## - `uint <system.html#uint>`_ on Linux, macOS and other platforms that use the
+      ##    LP64 or ILP32 `data models
+      ## <https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models>`_.
+      ##
+      ## .. warning:: The underlying Nim type is an implementation detail and
+      ##    should not be relied upon.
+elif defined(windows):
   type
     clong* {.importc: "long", nodecl.} = int32
-      ## This is the same as the type `long` in *C*.
     culong* {.importc: "unsigned long", nodecl.} = uint32
-      ## This is the same as the type `unsigned long` in *C*.
 else:
   type
     clong* {.importc: "long", nodecl.} = int
-      ## This is the same as the type `long` in *C*.
     culong* {.importc: "unsigned long", nodecl.} = uint
-      ## This is the same as the type `unsigned long` in *C*.
 
 type # these work for most platforms:
   cchar* {.importc: "char", nodecl.} = char
@@ -51,8 +83,7 @@ type # these work for most platforms:
     ## This is the same as the type `long double` in *C*.
     ## This C type is not supported by Nim's code generator.
 
-  cuchar* {.importc: "unsigned char", nodecl, deprecated: "use `char` or `uint8` instead".} = char
-    ## Deprecated: Use `uint8` instead.
+  cuchar* {.importc: "unsigned char", nodecl, deprecated: "Use `char` or `uint8` instead".} = char
   cushort* {.importc: "unsigned short", nodecl.} = uint16
     ## This is the same as the type `unsigned short` in *C*.
   cuint* {.importc: "unsigned int", nodecl.} = uint32