libsdl-org
stdinc: Document maths functions
Currently, SDL_stdinc.h has a documentation comment for SDL_acos(), but nothing else.
We should expand on that comment, and add comments for the remaining maths functions. This provides examples for the first few, in a format that seems okay to me.
In particular, note that functions like SDL_exp() are not expected to give the same result across different setups, as mentioned in #8948.
This draft only covers up to SDL_expf() -- if the idea and format looks sound, I can add the remaining ones. Also, since we can just use the platform implementations, I'm not 100% sure the descriptions are prefectly correct for all possible implementations, but should be.
This seems fine. It seems a little verbose and filled with unnecessary warnings, but I'm not opposed to it. @icculus, thoughts?
It is verbose, which can be unpleasant for reading the header to absorb the API, but it's very useful for generating standalone wiki and man pages.
We could put a (non-Doxygen) comment at the top of the file that says something like "this is basically the most important bits of the C runtime for game development. In most cases you can just prepend SDL_ to the the usual function names and not study this header too deeply." :)
It is verbose, which can be unpleasant for reading the header to absorb the API, but it's very useful for generating standalone wiki and man pages.
Is it possible to put this documentation somewhere else in the file and link to it? Doxygen's @fn is made for that.
Yeah: I definitely was inspired by the MSDN and glibc man pages for these functions (as well as the one existing acos comment), so they're more 'reference manual' than 'quick comment' in style. I also wanted to get all of the cross-references right for the wiki.
I've gone ahead and filled in the rest of these, with a few minor changes to make them less verbose (i.e., remove the "Use this function to" prefix on everything).
I also added a note to the overall page documentation saying that these are just CRT functions.
Is it possible to put this documentation somewhere else in the file and link to it? Doxygen's @fn is made for that.
That'd be fine by me, too, though I think we'd want to be able to put a small (non-doc?) comment next to some functions if we moved the main documentation elsewhere. SDL_hints.h, for instance, also has a lot of detail for every hint, but would be pretty useless if there were no documentation in that file at all.