Gregory's ServerC library functions are always like: "SYNOPSIS. This function converts foos into bars depending on the user locale. ARGUMENTS. src and dest pointers must be distinct; it is undefined behavior if they are not QPU-aligned. RETURN VALUE. Returns the number of foos converted. A zero value indicates failure, or that zero foos were converted. A negative value indicates that the final foo was only partially converted (function got tired). Check this global variable to find out why."
 24 comments
 @typeswitch The exact type of C I have spent 20+ years intentionally avoiding writing.  @mos_8502 @typeswitch All that being said, I still like the man-page formatting for reference documentation. You can have the most pristinely architected C code in the world, but if I can't wrap my head around the over-arching architecture and/or how pieces fit together, the first place I will go to will be the API documentation for help. @mos_8502 @typeswitch I've never programmed in C professionally, but love me some good software engineering. What do you mean by "manual retain release" and "deinit" functions? Do you have any example I can learn from?  @typeswitch@gamedev.lgbt function got tired? more like "function got distracted by other things" according to how Unix syscalls were designed  @typeswitch @thephd You forgot "flags is a bit mask of 22 bits some of which can be used together and some of which can not which make this function do totally different things"  @smurthys @typeswitch @thephd The best part is that this isn't even really much of a straw man. https://learn.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte @malwareminigun @typeswitch @thephd The beloved `dwFlags` parameter. These two gems on that page, are just 😗: The function performs more quickly when none of these flags is set. If all three values are not provided, some results will be missing.  @malwareminigun @smurthys @typeswitch @thephd the win32 is pretty great, the size of it all means it contains just about every API design issue one can think of, now, in hindsight 😀 I do actually like it overall though @Paxxi I didn't intend to rip on Win32 specifically here; lots of C APIs are horrible. And I'll take a lot of these to one fork(). An API that looks basic but has far-reaching implications, makes accurate memory use tracking impossible, and generally creates cross cutting costs against the whole system. Whereas these examples are contained to only their immediate callers. @malwareminigun @typeswitch @thephd a personal favorite is "given this flag, the type of parameter 3 changes from T* to T**"  @typeswitch@gamedev.lgbt also the flags argument that is explained in the man page for a completely different function :') @typeswitch Actual comment from a C library I'm working on.  @typeswitch Honestly I rather have this than some doxygen badly rendering on mobile, saying things like "Factory for ElementManager" for classes named "ElementManagerFactory" as documentation to figure out why my application segfaults again  @typeswitch ERRORS. EUNRDBL can occur if any of the following five conditions occur:
|
@typeswitch it sounds bad BUT you can target this code to not work on multiple platforms in multiple distinct ways