document private functions

[goatshriek]

In the early stages of development of stumpless, documentation of private functions was not always done, as these are not exposed to library users. However, as the library has grown and more contributors have participated, the need for documentation of private routines is becoming more real.

This is a general issue to track documentation of the private functions, and is open to anyone who wishes to contribute without writing new code, but rather simply wants to read existing code and understand it. Go through the header files in include/private and add a doxygen-style comment for functions that currently don't have one. Be particularly careful to cover the POSIX safety of the function, which outline the thread, signal, and asynchronous cancellation safety of the function. Look to other functions for examples of the formatting - all functions in the include/stumpless headers are documented already. You can find the implementation of all functions in the file in the src directory corresponding to the header file.

In order for a pull request to be accepted regarding this issue, please document at a minimum three (3) functions, but the more the better, of course!

[vanshiz]

Please assign me this.

[goatshriek]

Hi @vanshiz, thank you for your interest and for reaching out!

This issue is a general placeholder, so it won't be assigned to anyone specifically. If you'd like an issue assigned to you so others can see what you're working on, feel free to open a separate one listing the specific functions you intend to cover.

It's also completely acceptable to open a PR without your own issue, if opening a new one feels like too much trouble.