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
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
