Documenting with Doxygen

I'm considering using Doxygen to document my project. Have been toying with it and am quiet impressed at the features. However the code can soon become unreadable. True, not everything needs to be documented, but I'm more interested in it to document:

• Areas of the code which need or could to be improved;
• Why I made certain choices in code;
• Explain more complex hierarchies;
• Tutor myself by providing explanations to certain areas of the code of which I have little knowledge yet.
• Explain less obvious code.
• Document my classes. (this is mostly /brief descriptions)

So the documentation can soon render my code unreadable on more sensitive areas.

What do you advise?
Opening a new branch just for documenting?
Keep Doxygen out of it since, while an interesting tool, bloats the code too much?
Do everything in the trunk and limit my comments to /brief the best I can?
Just use Doxygen as a code reporting tool and do my comments in C++ fashion?

Personally, I think that something like Doxygen is best used for documenting functions, classes, and their intended uses and behaviors. It shouldn't have excerpts from within code blocks explaining why you chose a specific function or something around those lines.

Quote:

---

the code can soon become unreadable.

---

I think it's very hard for too much commenting to get in the way of code readability. If you're not too attached to your coloring scheme, you can color comments to your advantage. I use the old Borland colors which had white keywords, yellow identifiers, and gray comments on a blue background. They gray comments are very easy to ignore when quickly scanning through lines of code.

True.

I use a color scheme based on the old terminals. Green on black. With white keywords, red numbers and dark grey comments. My workmates got disgusted at seeing me programm in VB like this...

Comments hardly get on my way. However... too much may not affect readability per se, but be distracting, which is certainly not good.

Quote:

---

It shouldn't have excerpts from within code blocks explaining why you chose a specific function or something around those lines.

---

Actually I always found that one of the best reasons to put a comment on my comment. Although I do see your point... on the other hand, it has no place in documenting.

Doxygen is really, in my opinion, for API documentation, i.e. you write a library and want others to understand how to use each function. Use normal comments to explain how your code works, and use completely separate text documents (whatever form you prefer - plain, docbook, latex, html, quickbook, ...) for the high-level documentation.

Well, not an API, CornedBee, but I do plan to have the code distributed within 6 months after which I'm hoping to slowly create a development team.