Where to document code with Doxygen

Question

Hello. I've never written documentation for any C-style code before (only done asdoc and phpdoc). I've been looking at Doxygen for documenting my Objective-C code, but I'm unsure where to put the comments. Should I document the .h files or should I add the comments to the .m files? or both? Any other recommendations?

Answer 1

Look at the doxygen documentation of some projects to see what they do.

http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/ is one that impressed me, but I'm sure you can find an objective-c project that does a good job.

API documentation goes in the .h file. You might have some implementation details that are worth documenting so you'll have some in the .m file as well. Just don't repeat yourself.

Avoid repeating what your code is already saying.

Answer 2

Your comments generally belong in the .h files, since those are what people look at to figure out how to use your classes.

Here is a more in-depth example of how to use Doxygen specifically with Objective C

Answer 3

As a convention, comments are to be placed in header files (*.h), because they mostly contains declarations and they are easier to read.

The documentation into the source files (*.m) is useful when there is no associated header files: for example, when you are using a private category for a class.

Moreover, Doxygen has some options that will print some warnings if some stuff are not or not enough documented.

Edit:

Here are a link to a tutorial called Documenting Objective-C with Doxygen.