[webkit-dev] API documentation in cpp files

[Darin Adler]

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 WebKit API header files, files intended to be used by the clients of WebKit outside the project, I think your proposal makes sense. For an example of a header file in WebKit that is done in this way, you could look at JavaScriptCore/API/JSObjectRef.h.

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.

    -- Darin