Pro-source: cscope's Find this global definition feature takes you to the source file (where the definition is) rather than the header file (where the declaration is).Pro-header: Code folding can help make commented headers more navigable by hiding the comments.When answering, please be wary of arguments based on what tools and "modern IDEs" can do. It pairs the documentation of a function with its implementation, making it easier to see that a function does what it says it does.It makes the header a lot shorter, giving the reader a birds-eye view of the module as a whole.This keeps interface and implementation further apart.The source may be inconvenient, or even impossible, to acquire.The user doesn't need the source code to see the documentation.I am leaning toward documenting in the source file, so my "Pro-header" arguments may be somewhat weak. I'm only talking about things that are declared in a header file and defined in a source file. Note that some things are defined in the header only, such as structs, macros, and static inline functions. * No error checks here, c must point to a long-enough string. * This is a one-character version of pg_utf2wchar_with_len. * Convert a UTF-8 character to a Unicode code point. * printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec) In languages that distinguish between a "source" and "header" file (mainly C and C++), is it better to document functions in the header file:
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |