move function documentation to header

[alibabashack]

I passionately dislike libraries, which put the user API documentation into the c files. It clearly belongs into the header files, where the user (or users IDE) can find it, even when precompiled lib + headers are used. In addition there might be several implementations for different architectures in the future, each having its c file. Still you want a common interface definition for them maintained in a single set of headers.

This is of course a kind suggestion, but with a strong opinion ;-)

[mateunho]

Pal uses doxygen for documenting code. It's output is considered as a standalone product (pdf, html, etc.) you can view without source code, hence your previous argument is, kinda, invalid 😛

I agree with your point that having docs in header files makes it easier with maintenance. Particularly in case of multiple definitions for different architectures. However, even at this point of development, pal is a huge library, so moving docs to headers would be a tedious job 😫, which I, presonally, would not take up.