Where to put doxygen comments

I’m awesome
This is an “ah ha!” moment for me. For some reason, I felt that it was better to place all of my function method comments inside the cpp files instead of the header file. I felt it was cleaner, and it looked nicer because the header file was nice and compact and formatted neatly. You could glance at the class and immediately determine what public function methods you were supposed to use.

I am no longer awesome like I thought
Well, until I realized that, after you compile the library and distribute it with the header file, there are zero comments for the end user on how to use the API, unless you’ve built the doxygen comments already and also distributed it. This makes it a hassle for the developer who now has to go onto a website or open a .chm file for documentation. It’s rather clumsy.

There is a nasty trade off for this though. If you put all the comments in the header file, the user may now have to scroll around just to find the public API. It may not be nice and neat anymore and it feels cluttered to me. Maybe you can use visual studio’s “#region” stuff to help though.

Put doxy comments inside the header file for the end user, not the cpp file, where no one will be looking or possibly even have access to. Alternatively, put the comments in the cpp file, but make sure you’ve built the doxygen documentation for the API. I say the header is better because the developer won’t have to jump out to a website to get documentation. Another rason is because you can mouse over a function in visual studio and it gives you a synopsis of it with the tool tip. Yay.