On 03/17/2013 04:48 PM, John Scipione wrote:
On Sun, Mar 17, 2013 at 4:53 AM, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx> wrote:On 03/16/2013 10:12 PM, jscipione@xxxxxxxxx wrote:* We don't detail private function in the Haiku book and this class has a bunch so keep the documentation in the file but use regular comments instead.Please don't do that -- we use doxygen style for private functions everywhere. And while they don't end up in the Haiku book, there is no reason we'll never create a class documentation for it.If we really use doxygen style for private functions everywhere then we should put them in the Haiku book.
No one said "everywhere". IMO it doesn't make much sense to document functions whose name and signature are obvious. However there are functions that have a rather complex or at least not entirely obvious interface (if you look around in the kernel sources you'll find quite a few).
Anyway, being private functions/methods, their documentation really doesn't belong in the HaikuBook. The docs are only for the developers using the those functions.
I don't see an API docs for private functions ever happening, either we document them in the Haiku book or we document them in the source, and if we document them in the source, there's no reason to use doxygen style comments as it clutters the code for no gain.
With doxygen comments we have a well-defined style how to document the interface of a function or class. When we want to document the interface, why would we use a different style? Commenting the source (i.e. the implementation) of a function/method is a completely different thing. Those comments are for the benefit of the developers reading/changing the source of such a function.
CU, Ingo
