[webkit-dev] API documentation in cpp files
darin at apple.com
Wed Jun 22 09:27:56 PDT 2011
On Jun 22, 2011, at 7:29 AM, Grzesiek Czajkowski wrote:
> I am wondering why webkit has the most documentation in cpp files. In header files only classes, structures are documented. Is there any reason to do it in that way?
> If we will have all documentation in header files client programmer will take devel package of webkit and he may generate a documentation by doxygen command. He doesn't need the sources of WebKit.
For the vast majority of WebKit’s source file, the internals, I believe that filling them with extensive doxygen-style header comments would make it harder to understand the code.
In general my preference is to have comments that say things that the code does not. Many header comments I have seen repeat things already said by the names and signatures of functions. Comments that answer questions such as "why" and that are brief would make a good addition, even to a header file.
More information about the webkit-dev