Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

move function documentation to header #75

Open
alibabashack opened this issue Jun 4, 2015 · 1 comment
Open

move function documentation to header #75

alibabashack opened this issue Jun 4, 2015 · 1 comment

Comments

@alibabashack
Copy link

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
Copy link
Contributor

mateunho commented Jun 4, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants