Foreign.C.Types, potentially misleading haddock documentation (on e.g. hackage.org)
Summary
Location of documentation issue: The Haddocks of base
(Specifically Foreign.C.Types)
When haddock produces documentation for platform-specific C types, the configure.ac macros that determine the corresponding Haskell types (e.g. CInt -> Int32 on most platforms) are already expanded, and so the hackage.org document reads (e.g. https://hackage.haskell.org/package/base-4.12.0.0/docs/Foreign-C-Types.html#t:CInt):
newtype CInt
Haskell type representing the C int type.
Constructors
CInt Int32
which can mislead users to conclude that the representation is always Int32
, but this is not necessarily the case, and even more likely for some of the other types.
While a savvy reader may correctly infer that Haskell type representing the C int type means that the type is platform dependent, and the Int32
is not necessarily dispositive, I do think that there is real room here for confusion, especially for users better versed in Haskell than C.
Proposed improvements or changes
Perhaps just some text in the short description of each such type that mentions that the representation is platform-specific, and should not be assumed to match what haddock happens to document for the platform on which it ran.